ProGuide ArcGIS Pro Extensions NuGet - kataya/arcgis-pro-sdk GitHub Wiki

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          11/24/2020
ArcGIS Pro:    2.7
Visual Studio: 2017, 2019

Beginning with ArcGIS Pro 2.4, an ArcGIS Pro Extensions NuGet is available on the Nuget Gallery. Esri.ArcGISPro.Extensions. 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.

• Introduction
• Requirements
• Install instructions
  • Signing Add-ins on a Build Server
• Using the ArcGIS Pro Extensions NuGet
• Benefits of the ArcGIS Pro Extension NuGet
• Use 2.4 NuGet with older versions of ArcGIS Pro SDK projects

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.

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.
• As of Pro 2.5, .Net Target Framework must be set to 4.8. This is important if you are adding the Nuget to a pre 2.5 add-in project.

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

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.

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, and its two dependencies: DADFLib.dll and zlibwapi.dll, to your build server (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.

The ArcGIS Pro Extensions 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.

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).
  • 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.
    
• 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.

If you have an add-in or configuration project that was created with an older version of the Pro SDK (older than 2.3), you can still use the 2.4* ArcGIS Pro Extensions NuGet by following the steps below to modify your project file.

1. In Visual Studio in the Solution Explorer, right click the add-in or configuration project node. Select Unload Project from the context menu.

2. After the project is unloaded, right click the project node again to access the context menu. Click Edit <Project Name> menu item.

3. The .csproj (or .vbproj) file will open in Visual Studio editor. Scroll to the bottom of this file and locate the action that checks for the existence of the Esri.ProApp.SDK.Desktop.targets file within the "Before Build" target. It should look like this:

    <Target Name="BeforeBuild">
    <Error Text="C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets not found." Condition="!Exists('C:\Program Files\ArcGIS\Pro\bin\Esri.ProApp.SDK.Desktop.targets')" />
    </Target>

4. The Error action above needs to be commented so that it does not execute. To comment out this, modify these lines so it looks likes the code snippet below:

   <!--<Target Name="BeforeBuild">
   <Error Text="$arcgis$bin\Esri.ProApp.SDK.Desktop.targets not found." Condition="!Exists('$arcgis$bin\Esri.ProApp.SDK.Desktop.targets') AND !Exists('Esri.ArcGISPro.Extensions.targets')" />
   </Target>-->

5. Save your edits to the project file.

6. Right click the project node again in Solution Explorer and select Reload project.

7. Delete the references to the Esri.* Pro assemblies and install the ArcGIS Pro Extensions NuGet using the Installation Instructions.

8. Build your project.

Note: to maintain consistent Add-in desktop versioning you should change the desktopVersion in your add-in Config.daml to 2.4. Consult ProConcepts Advanced Topics "Add-in-versioning" for details.

*To use the Pro 2.5 Nuget or better you must also change your add-in project .Net Target Framework to 4.8.