ProGuide Command line switches for ArcGISPro.exe - 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

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] [/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
/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.

ArcGISPro.exe /config:ProConfiguration1

loads the configuration ProConfiguration1.proConfigX at Pro startup.

ArcGIS Pro supports a diagnostic mode that is enabled through the following command line switch:

ArcGISPro.exe /enablediagnostics

The mode provides a simple, single application wide logging facility (file based). Each logged event is simply 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).

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 an ArcGIS\Diagnostics subfolder.  The log file itself is called ArcGISProLog.xml.  If the log ever exceeds 10 MB, older entries will be aged out of the log.

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
    {
      Error,
      Warning,
      Information
    }

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

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

When running Pro in diagnostic mode with the Pro, a debug file "CEF.log" will be written to your <UserName>\Documents\ArcGIS\Diagnostics directory (in addition to the ArcGISProLog.xml log file). Use CEF.log to debug Chromium web browser control issues.

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:\Documents\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