Esri.ArcGISPro.Extensions30 3.1.0.41833

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          12/21/2022
ArcGIS Pro:    3.1
Visual Studio: 2022

ArcGIS Pro Extensions30 NuGet

An ArcGIS Pro Extensions30 NuGet (Esri.ArcGISPro.Extensions30) is available on the NuGet Gallery. The Pro NuGet contains all the Pro API assemblies needed to compile your Add-ins and Configurations. 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.

Note: At ArcGIS Pro 3.0, there is a new ArcGIS Pro extensions NuGet called Esri.ArcGISPro.Extensions30. If you are migrating an Add-in or Configuration from 2.x to 3.0 using the Pro Migration tool, and if the project includes the 2.x NuGet, the NuGet reference will be automatically be updated to Esri.ArcGISPro.Extensions30.

In this topic

• Introduction
• Requirements
• Install instructions
  • Signing Add-ins on a Build Server
• Using the ArcGIS Pro Extensions30 NuGet
• Benefits of the ArcGIS Pro Extension NuGet

Introduction

ArcGIS Pro Extensions30 NuGet contains the ArcGIS Pro extension assemblies needed to compile your Add-ins and Configurations for ArcGIS Pro versions 3.0 and higher. The NuGet 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 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 Extensions30 NuGet will only work with the NuGet Package Management format setting in Visual Studio must be PackageReference.

The 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 for more information on Pro API assembly references and Copy Local.

Install instructions

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

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

2. Select all the ArcGIS.* assembly references, right click and pick "Remove" from the context menu. Also select the ESRI.ArcGIS.ItemIndex assembly, right click and pick "Remove". This will remove all the ArcGIS Pro file based references from your project. You are going to replace these references with the ArcGIS Pro Extensions30 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 Extensions30" in the Search text box.

9. Select the Esri.ArcGISPro.Extensions30 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 Extensions30.

12. Close the NuGet Package manager dialog.

13. In your Solution Explorer in Visual Studio, expand the Dependencies > Packages node. Notice that the Esri.ArcGISPro.Extensions is now listed as a NuGet reference.
    <img src="https://ArcGIS.github.io/arcgis-pro-sdk/images/ProGuideNuGets/ReferenceNuGet.png" width="50%">

14. Compile your Add-in or Configuration project. The compilation will now use the ArcGIS Pro Extensions30 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.

Signing Add-ins on a Build Server

If you sign your add-in or configuration during the compilation process on your build server, you will also need ArcGISSignAddIn.exe. This executable is part of the standard ArcGIS Pro installation and is not included with the NuGet. To sign an add-in on a build server configuration, copy ArcGISSignAddIn.exe, ArcGISSignAddIn.dll, ArcGISSignAddIn.runtimeconfig.json and DADFLib.dll to your build server bin folder (the folder location is irrelevant just make sure they are copied together). Note: If you do not want to reference ArcGISSignAddIn.exe with a fully qualified path make sure whichever folder you copy it and its dependencies to gets added to the server's Path environment variable.

Alternatively, you can download the ArcGISSignAddIn.zip file from the ArcGIS Pro SDK Resource download location. This zip file contains the files you will need to sign the add-in/configuration on a build server. Unzip to a folder location of your choice and (optionally) add the location to the server's Path environment variable.

Using the the ArcGIS Pro Extensions30 NuGet

The ArcGIS Pro Extensions30 NuGet is intended for use with ArcGIS Pro add-ins and configurations only. As the NuGet contains the Pro public extension APIs, it should not be referenced in core host applications and Pro plugins which are intended for use with the ArcGIS.Core geodatabase and geometry APIs and not the Pro extensions.

Technically speaking, if a core host application or a Pro Plugin does use the NuGet, it will still compile. However, if they reference any of the extension APIs (contained in the NuGet) within their code then they will crash at runtime.

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 Extensions30 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).
  • This is for build only. Registering your Add-in always requires the presence of RegisterAddin.exe and a Pro install.
  • If you build an add-in or configuration project without ArcGIS Pro installed, you will get a warning that ArcGIS.Desktop.Framework.xsd schema is not found. This is the schema that is used for the Config.daml file included in the add-in and configuration project. This should not affect the compilation process.
    <img src="https://ArcGIS.github.io/arcgis-pro-sdk/images/ProGuideNuGets/schemawarning.png">
• Build add-ins easily against different versions of ArcGIS Pro: Assuming that, over time, multiple versions of the ArcGIS Pro Extensions30 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 Extensions30 NuGet and toggle between available versions using the "Version:" combo on the tab.