ProGuide writing an addin with copilot

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          10/30/2025
ArcGIS Pro:    3.6
Visual Studio: 2022

This ProGuide explains how to configure and use Visual Studio with GitHub Copilot to develop ArcGIS Pro addins. This guide has two main sections:

• Setting up a GitHub Repository and GitHub Copilot for ArcGIS Pro Add-in Development
  The steps outlined in this section are prerequisites to using GitHub Copilot and only need to be performed once before developing Add-ins or other ArcGIS Pro extensions.
• Using GitHub Copilot to develop an ArcGIS Pro Add-in
  The steps outlined in this section show a sample addin development workflow using GitHub Copilot.

Prerequisites
To use GitHub Copilot within Visual Studio, you need to meet the following requirements:

• A GitHub account: You need a GitHub account to use GitHub Copilot. If you don't have one, you can sign up for free at GitHub.
• Sign up for a GitHub Copilot plan or subscription: GitHub Copilot is a paid service, but it offers a free trial period.
• In order to test this Add-in, a sample dataset has been provided that can be downloaded from: https://github.com/Esri/arcgis-pro-sdk-community-samples/releases specifically the release asset called: "CommunitySampleData-3D-11-21-2025.zip" which contains an ArcGIS Pro project called 'Elevation\HawaiiElevation.aprx'. This project contains all feature layers and test data needed to test the Add-in created in this ProGuide.

Setting up a GitHub Repository and GitHub Copilot for ArcGIS Pro Add-in Development

Step 1 Setting up GitHub Copilot in Visual Studio

• Visual Studio: GitHub Copilot provides an optional Visual Studio Extension for Visual Studio 2022 (Version 17.10 or later) that must be installed.
• For Visual Studio 2026, Copilot is installed automatically.

Step 2 Visual Studio GitHub Copilot Sign-in

• In Visual Studio, sign in using your GitHub account with an active Copilot subscription.
• Make your GitHub account the active account in Visual Studio.
• If your GitHub account has an active Copilot subscription, you will be signed in to GitHub Copilot and Visual Studio will display the 'GitHub Copilot is Active' icon at the top right.

Step 3 Create a new GitHub Repository

• On GitHub, create a new repository to store your ArcGIS Pro Add-in project. The repository can be made private to restrict access to the code.
• Make sure to initialize the repository with the 'Visual Studio' .gitignore file to exclude files that should not be included in the repository.

Step 4 Clone the GitHub Repository on your local machine

• In Visual Studio, clone the GitHub repository you created in Step 3 to your local machine. You can use the 'Code' drop-down on the GitHub repository page to clone the repository directly into Visual Studio.

Step 5 Tuning Copilot with MCP Server
The GitHub MCP (Model Context Protocol) server enables seamless integration of AI capabilities with GitHub. Connecting your development machine to a GitHub MCP server enables Copilot to access repositories on GitHub, such as the Esri/arcgis-pro-sdk-community-samples repository.

If GitHub MCP has already been set up on your machine, you can skip to Step 6. Otherwise, perform the following setup instructions for the GitHub MCP server in GitHub Copilot for Visual Studio. It is best to start out with the GitHub MCP remote server, which is hosted by GitHub and requires no local setup:

• Requires Visual Studio 2022 version 17.14.9 or later.
• The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.

1. Create a new file with the file name .mcp.json in your solution or %USERPROFILE% directory.
2. Add this configuration to the newly created JSON file:

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

3. Save the file. Restart Visual Studio and open the 'MCP Registries' window that is now available under Extensions > MCP Registries. Make sure that the github/github-mcp-server extension has been installed.
4. In the GitHub Copilot Chat window in Visual Studio, switch to Agent mode.
5. Authenticate 'github' and 'github/github-mcp-server' using the settings button in the Copilot Chat prompt as shown here. Also make sure that your check-boxes for both items are checked.

Step 6 Tuning Copilot with custom instructions

1. Create a custom instructions file .github/copilot-instructions.md in the root folder of your local repository and initialize the copilot-instructions.md file with the following content:

# Copilot Custom Instructions for ArcGIS Pro SDK Add-in Development

I am developing ArcGIS Pro Add-ins using the ArcGIS Pro SDK.

- Use the authoritative ArcGIS Pro SDK API documentation as the primary reference: https://github.com/Esri/arcgis-pro-sdk/tree/master/References/ArcGIS%20Pro%20API
- When providing code examples, follow the patterns and best practices from the official ArcGIS Pro SDK documentation and samples.
- Prefer C# for all code snippets and explanations.
- Reference and leverage the code snippets available at: https://github.com/Esri/arcgis-pro-sdk-snippets and at: https://github.com/Esri/arcgis-pro-sdk
- Assume the development environment is Visual Studio 2022 or later.
- Use a tab size as defined in the Visual Studio settings (usually 2 spaces).
- To open ArcGIS Pro items, use the OpenItemDialog rather than the standard OpenFileDialog.
- To display a message box, use the ArcGIS.Desktop.Framework.Dialogs.MessageBox class.
- Use modern .NET and ArcGIS Pro SDK conventions.
- Use the https://github.com/esri/arcgis-pro-sdk/References/ArcGIS.Desktop.Framework.xsd xml schema when making changes to any config.daml desktop add-in markup language file.
- For UI development, use the MVVM (Model-View-ViewModel) programming pattern as recommended by the ArcGIS Pro SDK.
- When possible, provide concise explanations and relevant links to documentation.
- If a task involves UI, follow the ArcGIS Pro Add-in UI guidelines.

Always ensure that code suggestions are compatible with the latest supported version of ArGIS Pro SDK.

2. Enable the feature in Visual Studio via Tools > Options > GitHub > Copilot > check this 'Copilot Chat' option: Enable custom instructions to be loaded from .github/copilot-instructions.md files and added to requests.

Using GitHub Copilot to develop an ArcGIS Pro Add-in

To demonstrate how to use GitHub Copilot to develop an ArcGIS Pro Add-in, we will create a sample Add-in that uses a DockPane to guide the user through a GIS workflow. The DockPane allows the user to select a parcel lot feature from the map, displaying the selected parcel's ID, and has a drop-down option to select the final multi-patch polygon resolution (0 - rough, through 100 - fine in 10 increments), finally the dock-pane contains a button to create a 3D representation of the selected parcel geometry and adds it as a multi-patch feature to the "Lot MultiPatch" layer. In order to test the Add-in, the 'Elevation\HawaiiElevation.aprx' project can be downloaded and used (see the Prerequisites section above for details).

Note: When using GitHub Copilot, any suggestions provided by Copilot depend on various factors and cannot be reliably duplicated. AI Models are continuously trained on large datasets and generate responses based on patterns learned from that data. User Interactions, context, and even timing can influence the output. Therefore, while this guide provides a structured approach to using GitHub Copilot for ArcGIS Pro Add-in development, the specific suggestions and code snippets you receive may vary from those shown here.

Step 1 Create a new ArcGIS Pro Add-in project

1. In Visual Studio, create a new ArcGIS Pro Add-in project in the local folder where you cloned the GitHub repository. To do so you can simply open the 'GitHub Copilot Chat' window in Visual Studio and type the following prompt:

Create a new c# ArcGIS Pro Module Add-in Project called MyCopilotAddin

2. Copilot lists the manual steps to create the project. Follow this manual steps to create the project. Copilot also provides a command line option to create the project, however, at the time this document was released the command line didn't work. Rebuild the project to make sure everything is working.

Step 2 Use GitHub Copilot to help documenting the Add-in
This ArcGIS Pro sample add-in uses a DockPane to guide the user through a GIS workflow. The DockPane allows the user to select a parcel lot feature from the map, displaying the selected parcel's ID, and has a drop-down option to select the final multi-patch polygon resolution (0 - rough, through 100 - fine in 10 increments), finally the dock-pane contains a button to initiate the 3D lot creation using the selected parcel lot as input.

1. Use GitHub Copilot to create a ReadMe.md file to describe the add-in, to do so type the following request in the 'GitHub Copilot Chat' window:

Create a README.md file to describe the add-in as follows: This ArcGIS Pro sample add-in uses a DockPane 
to guide the user through a GIS workflow.  The DockPane allows the user to select a parcel lot feature from the map, 
displaying the selected parcel's ID, and has a drop-down option to select the final multi-patch polygon
resolution (0 - rough, through 100 - fine in 10 increments), finally the dock-pane contains a button to initiate 
the 3D lot creation using the selected parcel lot as input.  

Note: In some cases you have to create an empty README.md file, make it the active document and then use the 'Apply' button in order to add the suggested text to the README.md file.

Step 3 Create the Add-In UI on the ArcGIS Pro ribbon
We add a tab, group, and button to the ArcGIS Pro ribbon to open the 'Show 3D lot creation' DockPane.

1. In the 'GitHub Copilot Chat' window type the following prompt:

Create a new ArcGIS Pro Tab on the ArcGIS Pro ribbon called '3D Lots' this tab contains a group called 'Lots creation'.  The 'Lots creation' group contains an ArcGIS Pro Button called 'Show 3D Lots Creation'.  None of the newly created controls shall appear on the AddInTab.

2. Examine the suggestions provided by Copilot and
3. accept the changes proposed by Copilot if the modification look correct. Also note that one of the next steps that Copilot outlines is: Implement the Show3DLotCreationButton class in your add-in C# code (see ArcGIS Pro SDK Button sample).

Step 4 Implement the Show3DLotCreationButton class

1. In the 'GitHub Copilot Chat' window type the following prompt:

Implement next steps.

2. In my case Copilot suggested the following stubbed implementation for the Show3DLotCreationButton class:

internal class Show3DLotCreationButton : Button
{
    protected override void OnClick()
    {
        // TODO: Implement logic to show the 3D Lots Creation DockPane or dialog
        // Example: DockPane activation (replace with your DockPane ID)
        // DockPane pane = FrameworkApplication.DockPaneManager.Find("MyCopilotAddin_3DLotCreationDockPane");
        // if (pane != null)
        //     pane.Activate();

        // For now, show a simple message box as a placeholder
        MessageBox.Show("Show 3D Lots Creation button clicked.");
    }
}

3. Check the suggested code and accept it if it looks correct. Run the Add-in to verify that the 'Show 3D Lots Creation' button appears on the ArcGIS Pro ribbon under the '3D Lots' tab and 'Lots creation' group.

Step 5 Create the Dockpane for the addin
We add a tab, group, and button to the ArcGIS Pro ribbon to open the 'Show 3D lot creation' DockPane.

1. In the 'GitHub Copilot Chat' window type the following prompt:

Create a DockPane with a text box to display the selected parcel ID, a drop-down to select the multi-patch resolution 
(0 - rough, through 100 - fine in 10 increments), and a button to create the 3D lot.

2. Examine the suggestions provided by Copilot and
3. accept the suggestion if the code provided by Copilot is correct. Do not apply the addition of a new 'Show 3D Lots' button, since that button already exists. Note that Copilot provides updates to the config.daml and also creates the new files needed for the Dockpane MVVM.
4. Rebuild the project to make sure everything is working. In my case I had two errors a missing reference in the XAML file. I opened the XAML and asked Copilot:

Fix the missing StringNotEmptyConverter reference

5. or you can navigate to the compiler error and Ask Copilot to fix the error.
   
6. After accepting the changes rebuild the project again to verify that the errors have been fixed.
7. When i tested the Add-in in ArcGIS Pro the DockPane didn't open and an examination of the config.daml file showed that the dockPane tag was added to controls and not to the dockPanes tag. I asked Copilot to fix the config.daml file by typing the following prompt in the 'GitHub Copilot Chat' window:

The dockpane tag has to be added under the dockPanes tag and is missing the content tag

8. I accepted the suggestions and re-ran the Add-in to verify that the DockPane opened when clicking the 'Show 3D Lots Creation' button.

Step 6 Implement the DockPane ViewModel

First, we need to fill in the SelectedParcelId property to display the selected parcel ID from the 'Lots' feature layer in the DockPane. To do this, we need to listen to the selection changed event in the MapView.

1. In the GitHub Copilot Chat window, type the following prompt:

[Only add root namespace for ArcGIS.Desktop.]
In the DockPane ViewModel Subscribe to the MapView SelectionChanged event and use the first feature 
from the selection in the 'Lots' feature layer to query the 'Lots' feature layer for the 'Name' field value.
In the DockPane ViewModel update the SelectedParcelId property with that Name field value.
Use the MapSelectionChangedEvent class to do this.

Note: In my case, Copilot provided a complete implementation that worked correctly; however, it added all possible ArcGIS.Desktop namespaces to the DockPane ViewModel. To prevent this, I asked Copilot to "Only add root namespaces for ArcGIS.Desktop." This fixed the issue.

2. Rebuild the project to make sure everything is working. Run the Add-in, select a parcel in the 'Lots' feature layer, and verify that the selected parcel ID appears in the DockPane.

3. If you encounter errors, you can ask Copilot to help you fix them. I navigated to the error and asked Copilot to fix it; note that this can be an iterative process.

4. After accepting the changes, rebuild the project again to verify that the errors have been fixed. While debugging the feature selection, I noticed that Copilot didn't apply the QueuedTask.Run pattern properly. So I asked Copilot to fix this:

GetSelection has to be run within the context of QueuedTask.Run.

5. Rebuild the project to make sure everything is working. You should now see that the SelectedParcelId property is being set correctly when selecting a lot in the map.

Second, we need to implement the logic to create the 3D lot when the user clicks the "Create 3D Lot" button in the DockPane. This involves querying the selected parcel geometry, generating a multi-patch based on the selected resolution, and adding it to a new feature layer.

1. We need to remember the geometry of the selected parcel to do so type the following prompt in the Copilot Chat window:

In the dockpane view model create a new private property of the type Polygon named "SelectedGeometry".  
When assigning the parcelId also store the value in the "Shape" column which is of the type geometry and 
save a Clone of that geometry as a Polygon in the SelectedGeometry property.

2. Rebuild the project to make sure everything is working, you will need a break point to verify that the SelectedGeometry property is being set correctly.
3. Now we can implement the Create3DLot method. In the Copilot Chat window, type the following prompt:

The 'Create 3D Lot' button divides the selected parcel geometry into a grid of envelopes, clips the parcel geometry 
with each envelope,  and extrudes the resulting polygons to create a 3D multi-patch. 
The multi-patch is then added to the "Lot MultiPatch" feature layer  in the active map. 
If the "Lot MultiPatch" layer is not found, the operation is aborted.
The method requires a valid parcel geometry to be selected.
If no geometry is selected, a message box will notify  the user.
The resolution of the grid can be adjusted using the SelectedResolution property, with a default value of 10 if not specified.
The method also ensures that the "Lot MultiPatch" layer exists in the active map.
If the layer is not found, the operation is aborted, and the user is notified via a message box.
This method performs asynchronous operations, including geometry processing and interaction with the map's surface to retrieve Z values. 
It must be executed on the QueuedTask context to ensure thread safety when interacting with ArcGIS Pro's API.

4. Rebuild and run the project to make sure everything is working. Tilt the map to see the created 3D lot.