One of the great features of developing with ArcGIS Runtime is that you can download it and start developing as soon as you create a developer account. Of course, you will also see this watermark on your map until it is licensed:
You will also see a debug message in the Output window of Visual Studio. To have these messages removed from your app, you need to license it so that it meets Esri's license agreement terms. Let's discuss what kind of licensing options we have first, however. You have three licensing options:
You can develop and test using a Developer license at no cost. This is the kind of license you have once you download the SDK. A Developer license is not for deployment. A Basic license won't cost you anything, except that it has limited functionality. You can deploy with a Basic license. The Standard version of ArcGIS Runtime has a cost associated with it and it exposes all of the functionality of the API. You can also deploy with a Standard license. To determine this cost, you need to talk with your Esri representative. Otherwise, you can develop and test using a Developer license, without having to do anything else.
Let's look at the differences between the three license levels:
License level |
Functionality |
---|---|
Developer |
With this level of license, all functionality is available to you, except that you get the watermark, the debug statement, and the message you've seen with the San Francisco app we've built. |
Basic |
With this level of license, you get everything except the following functionalities:
|
Standard |
You get everything. |
Refer to the following screenshot for the message that you get in the Developer license:
So which license do you need? Well, if your app will only consume online services, or just view local content, you can get away with the Basic license. If your app, on the other hand, will do anything with local routing, address geocoding, editing, or syncing with a feature service, you'll need a Standard license.
As mentioned in the preceding section, you have two options that license the deployment of your app, so in this section, we'll go through the steps for each.
To license at the Basic level, you need to go back to the ArcGIS for Developers site:
App.xaml.cs
file that contains the start-up code for your app. It looks similar to this:public partial class App : Application { private void Application_Startup(object sender, StartupEventArgs e) { try { ArcGISRuntimeEnvironment.Initialize(); //ArcGISRuntimeEnvironment.ClientId = "<Your Client ID>"; } catch (Exception ex) { MessageBox.Show(ex.ToString(), "ArcGIS Runtime initialization failed."); // Exit application this.Shutdown(); } } }
ClientID
is set and past in your client ID from developers.arcgis.com
. Consider the following example:ArcGISRuntimeEnvironment.ClientId = "Wa7qYHoBb3FFYOzk";
For Standard-level licensing, you have two options:
To license your app using Portal or ArcGIS Online, you will need to follow these steps:
IdentityManager
class from Esri.ArcGISRuntime.Security
. This class allows you to pass in your organizational username/password and it will determine whether your account is authorized. You will also need to add a reference to Esri.ArcGISRuntime.Portal
:// Connect to ArcGIS Online or Portal for ArcGIS using organization // account try { // exception will be thrown here if bad credential ... var cred = await IdentityManager.Current.GenerateCredentialAsync( this.portalURL, this.username, this.password); // add the credential if it was generated successfully IdentityManager.Current.AddCredential(cred); // identity manager will automatically include an available credential when connecting (based on the server URL) portal = await ArcGISPortal.CreateAsync(new Uri(this.portalURL)); } catch (ArcGISWebException webExp) { var msg = "Could not log in. Please check credentials. Error code: " + webExp.Code; } // once connected, get the license info from the portal for the current user var licenseInfo = portal.ArcGISPortalInfo.LicenseInfo; // set the license using the static ArcGISRuntimeEnvironment class Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.License.SetLicense(licenseInfo); // get a JSON representation of the license info var licenseJSON = licenseInfo.ToJson(); // ... code here to save JSON license string locally ...
This code first uses the IdentityManager
class to generate a credential based on the URL to a Portal, username, and password. The Portal URL would be as follows if using ArcGIS Online:
https://www.arcgis.com/sharing/rest
Otherwise, you will need to specify the location of your on-premises Portal for ArcGIS. This will produce a JSON representation of your license.
Now that you have a JSON representation of the license, you need to provide that to your app, as shown here:
try { // set the client ID and initialize the ArcGIS Runtime Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.ClientId = " Wa7qYHoBb3FFYOzk "; Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.Initialize(); } catch (Exception ex) { Console.WriteLine("Unable to initialize the ArcGIS Runtime with the provided client ID: " + ex.Message); } try { // use the static FromJson method on LicenseInfo to create the // license var localLicenseInfo = LicenseInfo.FromJson(this.licenseJSON); // set the license Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.License.SetLicense( localLicenseInfo); } catch (Esri.ArcGISRuntime.LicenseException ex) { Console.WriteLine("Unable to license the ArcGIS Runtime with the license string provided: " + ex.Message); }
With this saved license code, you can now use the app offline for 30 days before you need to reconnect to Portal or ArcGIS Online. If the app is used beyond 30 days, it will only have the Basic license's functionality, which may cause an error if your app has the Standard license's functionality. As such, you will want to not call functionality where the Standard license's functionality is being used. With WPF, you could bind to a property that checks whether the license is valid or not.
To use an extension for a local server, such as 3D Analyst, you will now need to license your app for that extension using the following steps:
try { // set the client ID and initialize the ArcGIS Runtime Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.ClientId = "Wa7qYHoBb3FFYOzk"; Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.Initialize(); } catch (Exception ex) { Console.WriteLine("Unable to initialize the ArcGIS Runtime with the provided client ID: " + ex.Message); } try { // use the license code to enable standard level functionality Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.License.SetLicense("runtimestandard,101,rux00000,none,XXXXXXX"); } catch (Esri.ArcGISRuntime.LicenseException ex) { Console.WriteLine("Unable to license the ArcGIS Runtime with the license string provided: " + ex.Message); }
Esri.ArcGISRuntime.ArcGISRuntimeEnvironment.License.SetLicense( "runtimestandard,101,rux00000,none, XXXXXXX", "runtimespatial,101,rux00000,none, XXXXXXX", "runtimenetwork,101,rux00000,none, XXXXXXX", "runtime3d,101,rux00000,none, XXXXXXX");
Esri will provide the correct string to replace the X
instances. Your app will now run with a Standard license and include the ArcGIS extensions required for the local services.
As part of the license agreement with Esri, you need to perform the following steps:
Mapping API provided by Esri ArcGIS Runtime SDK for .NET
.Esri_StreetMap_World_2D
map service located at http://server.arcgisonline.com/arcgis/rest/services/ESRI_StreetMap_World_2D/MapServer.This text must appear in About or Credits in your app.
To meet the requirements for the Esri logo, the app must meet the following guidelines:
We have an app now. We're ready to deploy it to the targeted hardware. We've tested it and we've made sure it performs well. The next thing we need to do is figure out how to deploy it to the targeted device(s). Well, one of the great features of ArcGIS Runtime is that it can simply be copied from one device to another and it will just run, without having to create an installation program where you'd have to modify the registry. This of course doesn't include any data your app will need. Also, this doesn't include the fact that developing on Windows Desktop, Windows Store, or Windows Phone requires a different set of concepts and steps that account for the differences in these platforms.
Another great feature of ArcGIS Runtime is that you can pick and choose the options you need to deploy. As a result, if you don't need local services, you don't need to include them. This reduces the size of the deployment, which can be very important with devices such as Raspberry Pi, where disk space will be at a premium.
In the following sections, we'll address the steps you'll need to take to deploy your app.
You can create your deployment using the Visual Studio IDE. Let's take the Chapter1
project that you built in Chapter 1, Introduction to ArcGIS Runtime, and modify it so that you can deploy it:
Deployment.arcgisruntimemanifest
. It will look like this:As you can see from this screenshot, you can select the components to include in your deployment. The more options you include, the larger your deployment. A very nice feature with the manifest is that it will total up the size of your deployment for you and it provides the size of each item. If you don't need Specialized Symbology, don't include it. The ArcGIS Runtime checkbox is also checked; but as you can see in the preceding screenshot, it's only 54 MB. That's incredibly small! You will also note beside Selected size that this project is currently in debug mode and it's ready to be deployed as a 32-bit and 64-bit app. If you don't want to include a 32-bit option, change your project's Build settings to 64-bit. This will greatly reduce the size of the deployment. If you select Any CPU, a deployment for 32-bit, 64-bit, and ARM will be created.
Let's finalize this deployment with a few more steps:
C:ArcGISRuntimeBook
, and you'll note the following directory structure:This directory structure shows you that the 32-bit (client32
) and 64-bit deployments were created. You will also see many other two-letter folder names, such as cs
, that contain a single file called Esri.ArcGISRuntime.resources.dll
. These files contain the strings to support ArcGIS Runtime in a specific language.
Debug
directory and double-click on the app. It's called Chapter1.exe
. The app will run as it did in Visual Studio.It's also possible to deploy without a manifest file by manually performing the following steps:
.exe
file and any required supporting files (the data, 3D models, configuration files, and so on).Esri.ArcGISRuntime.dll
file to the deployment folder. This will be the same location as your .exe
file.ArcGISRuntime10.2.7
folder from the build
directory to the deployment folder.ArcGISRuntime10.2.7
folder, remove any unnecessary platform folders, such as Client64
.