ProGuide Command line switches for ArcGISPro.exe - Esri/arcgis-pro-sdk GitHub Wiki

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

This ProGuide explains the command line switches that can be used with ArcGISPro.exe. The command line switches can be used in any order or combination with the exception of project filename. If a project file name is specified, it must be last:

ArcGISPro.exe [/config:config_name] [/enablediagnostics {/loglevel=debug|information|warning|error}] 
              [/dumpcombineddaml] [/disableaddins] [project filename]

/config:config_name   Runs the named Managed Configuration on Pro startup (must be **first** argument)
/enablediagnostics    Launches ArcGIS Pro in diagnostic mode (default loglevel=information)
/dumpcombineddaml     Consolidates the DAML from all extensions and add-ins into one representation of the UI 
/disableaddins        Blocks all configurations and add-ins from loading.
project filename      Fullpath to an .aprx file to be opened by default

• Run the named Managed Configuration
• Enable dynamic mode event logging
• View the DAML elements loaded at start-up
• Block all add-ins and configurations from loading
• Open a project at start-up
• Custom command line arguments

ArcGIS Pro supports a special type of Add-in called a 'Managed Configuration' or Configuration for short. Managed configurations are installed to a well known folder (see Configuration Folders or to the default location: C:\Users\<userName>\Documents\ArcGIS\AddIns\ArcGISPro\Configurations. Only one configuration can be loaded by Pro per session and is specified using the /config:config_name command line argument.

The /config: switch must be the first argument on the ArcGISPro.exe command line or it will be ignored. The name of the configuration archive without the .proConfigX suffix should be specified as the config_name argument. config_name is case sensitive and it cannot contain spaces. For example, the following switch:

ArcGISPro.exe /config:ProConfiguration1

... loads the configuration ProConfiguration1.proConfigX at Pro startup.

ArcGIS Pro supports a diagnostic mode that is enabled either by opening the Diagnostic Monitor with ArcGIS Pro as the active window (using Ctrl + Alt + M), or by launching ArcGIS Pro with the following command line switch:

ArcGISPro.exe /enablediagnostics

ArcGISPro.exe /enablediagnostics /loglevel=debug

The mode provides a simple, single application wide logging facility (file based). An (optional) log level can also be specified from one of four values from most verbose (debug) to least verbose (error) - /loglevel=debug, /loglevel=information, /loglevel=warning, or /loglevel=error. The default loglevel, if one is not specified, is /loglevel=information.

Each logged event is a string with a time stamp and a type: warning, error, or information.  The log format and usage is similar to the Windows Event log but stored within an independent XML file.  Event strings can contain carriage returns and will be formatted neatly within the XML log file accordingly (see example below).

NOTE: When Diagnostic Mode is enabled and regardless of how you enabled it, Diagnostic Mode will remain enabled until ArcGIS Pro is closed.

Events written to the event log should be clear and unambiguous since they are intended to aid external users or developers in diagnosing issues. Like exception strings, diagnostic mode event strings are English only.

WARNING: You should never log strings to the event log that might contain identifying information, passwords, or confidential information.

A fresh, empty log file is created each time the application is started. The log file is created within the user’s Documents folder under the ArcGIS\Diagnostics subfolder. The log file itself follows a consistent naming convention. For example, you might see a log file named the following:

ArcGISProLog-16360~89343E4F-74E8-4F26-A705-B805E8C92BB0

Where:

• "ArcGISPro" is the host executable name
• "16360" is the PID/Process ID that is currently recording diagnostics
• "89343E4F-74E8-4F26-A705-B805E8C92BB0" is the unique ID created for that instance

A maximum of 15 log files will be saved & accessible from the ArcGIS\Diagnostics subfolder at any given time; when this threshold is exceeded, the oldest log(s) in this directory will be moved to the Recycling Bin automatically, where they can still be recovered for review if needed.

Example contents of a log:

<?xml version="1.0"?>
<EventLog ver="1">
  <Event time="Wed Oct 14 10:12:31 2015" type="Info">Application startup.</Event>
  <Event time="Wed Oct 14 10:12:38 2015" type="Error">
      An error was encountered when importing document “junk.mxd”.
      One or more layers were invalid.
  </Event>
</EventLog>

3rd parties can add their own output to the event log using the EventLog static class exposed from ArcGIS.Desktop.Framework.Utilities.  Note that calling EventLog.Write() is a no-op if diagnostic mode hasn’t been enabled. Therefore there is no need to write logic into your add-in to determine if you are in diagnostic mode or not. Events written to the log will be flushed to disk at application shutdown (even when an exception brings the app down), however, you have the option of writing them immediately if you want them to appear in the log file while the application is still running.

  //class located in ArcGIS.Desktop.Framework.Utilities
  public static class EventLog
  {
    public enum EventType
    {
      /// <summary>
      /// An event that indicates a significant problem such as loss of data or loss of functionality. 
      /// </summary>
      Error,

      /// <summary>
      /// An event that is not necessarily significant, but may indicate a possible future problem. 
      /// </summary>
      Warning,

      /// <summary>
      /// An event that describes the successful operation within the application.
      /// </summary>
      Information,

      /// <summary>
      /// An event that includes detailed information about an operation within the application.
      /// </summary>
      Debug
    }

    public static bool IsEnabled
    public static void Write(EventType type, string entry, string func, string code, unit elapsed, 
                               bool flush = false)
  }

 EventLog.Write(EventLog.EventType.Warning, 
   String.Format(
       "Add-In {0} disabled due to an exception during component initialization.", id));

The EventLog class also includes diagnostic counter methods which let you associate a count (or numeric value) with a named counter. When the application running in diagnostic mode terminates, all of the currently registered counters will appear in a report at the end of the log.

EventLog.IncrementCounter("MyCounterName");

ArcGIS Pro consolidates the DAML read from all extensions and add-ins into a single representation of the UI. The consolidated DAML file is written to the user's temp folder and is then launched in Notepad.exe.

ArcGISPro.exe /dumpcombineddaml

ArcGIS Pro will block all add-ins and configurations from loading.

ArcGISPro.exe /disableaddins

ArcGIS Pro project files (.aprx) can be opened via command line.

ArcGISPro.exe "C:\data\Project1.aprx"

Custom arguments or switches must be placed before the project file name argument (and after any /config:Configuration parameter). To access your custom command line arguments in your add-in, refer to ProSnippets Framework get-command-line-arguments