ProGuide ArcGIS Pro Extensions NuGet

Language:      C# and Visual Basic
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          12/28/2018
ArcGIS Pro:    2.3
Visual Studio: 2015, 2017

ArcGIS Pro Extensions Nuget Preview at 2.3

Beginning with ArcGIS Pro 2.3, a new ArcGIS Pro Extensions NuGet is available on the Nuget Gallery <<link to Nuget gallery here>>. The Pro Nuget contains all the Pro API assemblies needed to compile your Add-ins and Configurations. At 2.3, we are releasing the Pro Nuget as a preview only. During 2.3, we encourage you to try out the Nuget in your add-ins and configurations and to vote and comment on its usefulness <<using the poll link here>>. We will evaluate the votes and comments on the Nuget at the end of 2.3 to determine how useful it was to you (or not). If it does prove to be useful to you, the add-in developer, we will release the Nuget as part of our supported SDK at 2.4. If it is not useful then we will drop it. If we do support the use of the NuGet at 2.4, it will have no impact on the existing file-based references for Pro extensions. Use of file-based references will work in your Add-ins without change and we will continue to use file-based references as the default behavior of the Pro SDK templates when creating new Add-ins.

In this topic

• Introduction
• Requirements
• Install instructions
• Benefits of the ArcGIS Pro Extension NuGet

---

Introduction

NuGet packages are gaining in popularity within the .NET Developer community as a way to package and deploy libraries and to resolve assembly dependencies. The ArcGIS Pro Extensions NuGet contains all the Pro API assemblies needed to compile your Add-ins and Configurations and offers an alternate way to reference the ArcGIS Pro assemblies in your add-in and configuration over traditional file based references. To use the Nuget, simply delete out the existing Pro API assembly references and replace them with a reference to the Pro Nuget (per the installation instructions below). The guide will step you through the process of switching out the existing file based references with the Nuget as well as minimum requirements to use the Nuget and some additional benefits of using it as well.

Requirements

The ArcGIS Pro Extensions NuGet will only work with:

• Visual Studio 2017 update 8 or higher (Professional, Enterprise, and Community Editions)
• NuGet Package Management format setting in Visual Studio must be PackageReference.

The default NuGet Package Management format in Visual Studio needs to be PackageReference in order for the ArcGIS Pro Assemblies in the Nuget to be included correctly as references in your add-in or configuration project (the default is Packages.config which is incorrect). Within Visual Studio Select "Tools->Options->NuGet Package Manager->General" and change the Default package management format to PackageReference:

(This is also covered in Step 4 of the install instructions below). Use of `PackageReference` as the default Package Management format mimics the same semantics for the Nuget assemblies as if `Copy Local=False` were set on the individual assemblies directly. We (you) do **not** want copies of the Nuget assemblies copied into the local add-in Visual Studio project and the Pro assembly cache (i.e. `Copy Local=True` semantics which is the default Nuget behavior if the Package Management format is set to `Packages.config`). Refer to [ArcGIS Pro Assembly references in your project](ProConcepts-Advanced-Topics#arcgis-pro-assembly-references-in-your-project) for more information on Pro API assembly references and Copy Local.

Install instructions

The following provides detailed instructions for installing the ArcGIS Pro Extensions NuGet with your Add-In or Configuration project.

1. In Visual Studio, with your add-in or Configuration project open, expand the References node.

2. Select all the ArcGIS.* assembly references, right click and pick "Remove" from the context menu. This will remove all the ArcGIS Pro file based references from your project. You are going to replace these references with the ArcGIS Pro Extensions NuGet. (Steps below)

3. From the Visual Studio Tools menu, select NuGet Package Manager > Package Manager Setting menu item.

4. In the Options dialog, under NuGet Package Manager, select PackageReference from the drop-down for "Default Package Reference Format". Click OK to dismiss the Options dialog.

5. Right click the project node and select "Manage NuGet Packages.." from the context menu.

6. In the NuGet Package Manager dialog, confirm that the Package Source is set to "nuget.org" in the upper right corner.

7. Select the Browse tab.

8. Type "ArcGIS Pro Extensions" in the Search text box.

9. Select the Esri.ArcGISPro.Extensions NuGet package.

10. Confirm that the version drop down lists the "Latest Stable xxxx" version. Click the Install button.

11. View the License Agreement and click 'I Accept' assuming you want to complete the download and installation of the ArcGIS Pro Extensions.

12. Close the NuGet Package manager dialog.

13. In your Solution Explorer in Visual Studio, expand the References node. Notice that the Esri.ArcGISPro.Extensions is now listed as a NuGet reference.
    

14. Compile your Add-in or Configuration project. The compilation will now use the ArcGIS Pro Extensions NuGet.

Note: if, after adding the Nuget, you do not see a package reference but instead see a packages.config has been added to the project as well as copies of the ArcGIS Pro API assemblies check your NuGet Package Manager default package format (as explained in Step 4 and in the Requirements section above). Make sure the default package format is set to PackageReference. If it is set to PackageReference check your Visual Studio update level. It must be 8 or better.

Benefits of the ArcGIS Pro Extension NuGet:

There are a few benefits to using a NuGet package reference over file-based references other than a personal preference of one over the other:

• Sharing code: The Nuget package reference mechanism automatically handles resolving references via each user’s global Nuget cache. This enables sharing code amongst multiple developers, each with potentially different Pro installation locations (eg a D: drive vs a C: drive, etc.). With file based references the file references have to be "fixed" when projects are shared to accommodate the different Pro API assembly paths.
• Build-server and Continuous build scenarios: Since the ArcGIS Pro Extensions Nuget replaces the file based Pro assembly references, an installation of ArcGIS Pro is not required to build add-ins and configurations (as the references are self-contained in the Nuget rather than having to be physically located in an ArcGIS\bin\Extensions folder). Note: this is for build only. Registering your Add-in always requires the presence of RegisterAddin.exe and a Pro install.
• Build add-ins easily against different versions of ArcGIS Pro: Assuming that, over time, multiple versions of the ArcGIS Pro Extensions Nuget become available, the NuGet package manager in Visual Studio makes switching between different versions of the NuGet easy to accomplish. On the "Manage Nuget Packages for Solution..." tab select the ArcGIS Pro Extensions Nuget and toggle between available versions using the "Version:" combo on the tab.