Use dotMemory Command-Line Profiler

Last modified: 08 March 2021

There are multiple scenarios of how you can use the dotMemory command-line tool:

  • Profiling an application on a remote server.
    For example, this may be the case when it is not possible to install the standalone dotMemory to a server.

  • Automating the process of gathering memory snapshots.
    For example, if you want to make profiling a part of your continuous integration builds: this can be a build step that performs profiling of your integration tests.

  • Speeding up profiling routines.
    For example, when you regularly profile the same application and do not want to start the dotMemory user interface each time.

The dotMemory command-line tool can be used to profile any .NET or .NET Core application (including an already running one) and take memory snapshots.

Note that the tool is distributed free of charge as a .zip archive or NuGet package (Windows, Linux, macOS) and does not require dotMemory to be installed. You can freely upload it to any computer to take memory snapshots of problematic applications.

Main profiler commands:

  • get-snapshot- instantly get snapshot of a running app.

  • attach- attach the profiler to a running app and get snapshots by condition, using the API, or by sending commands to stdin.

  • start- start an app and get snapshots by condition, using the API, or by sending commands to stdin.

  • start-net-core- start a .NET Core app and get snapshots by condition, using the API, or by sending commands to stdin.

  • start-iis- (Windows only) start IIS and get snapshots by condition, using the API, or by sending commands to stdin.

  • start-iis-express- (Windows only) start IIS Express-hosted web application under profiling.

  • start-windows-service- (Windows only) (re)start managed Windows service under profiling and get memory snapshot by condition or using the API.

  • start-wcf-service- (Windows only) (re)start WCF host with specified WCF Service Library under profiling and get memory snapshot by condition or using the API.

  • start-winrt- (Windows only) start WinRT application under profiling and get memory snapshot by condition or using the API.

  • profile-new-processes- (Windows only) profile any managed application that is launched after executing this command.

  • list-iis-express- (Windows only) show the list of available IIS Express installations.

  • list-wcf-host- (Windows only) show the list of available WCF hosts.

  • list-winrt- (Windows only) show the list of available WinRT applications.

For the detailed information on a particular command, run: dotMemory.exe help <command> (Windows), ./dotMemory.sh help <command> (Linux, macOS).

This section covers only most basic tool usage scenarios:

Getting snapshot of a running application

It is the simplest and most demanded scenario. All you need is tell dotMemory which application you want to profile. You can do this in two ways: by application name, or by PID.

To instantly get a snapshot of a running application by its PID (e.g., 6844):

  • Run the command: 

    dotMemory.exe get-snapshot 6844 --save-to-dir=C:\Snapshots

Here:

  • --save-to-dir=C:\Snapshots- (optional) path to directory for saving a snapshot (more correctly, a workspace .dmw file). In this case, snapshot filename will be generated automatically. If you want to specify the filename by yourself, use the --save-to-file option.

  • 6844- process PID (you can find it in Window Task Manager).

To instantly get a snapshot of a running application by its name

  • Run the command: 

    dotMemory.exe get-snapshot MyApp --with-max-mem
    or 
    dotMemory.exe get-snapshot MyApp --all

Here:

  • MyApp- process name (you can find it in Windows Task Manager). If there are more than one process with such name, you can remove the ambiguity either with the --with-max-mem or --all option.

  • --with-max-mem- a process that consumes most of the memory will be profiled.

  • --all- all processes with the specified name will be profiled. dotMemory will take snapshots of all process (snapshot per process).

Starting application and getting snapshots by condition

Sometimes it may be necessary to track application memory consumption during a long time interval. In this case, you can start your application under profiling and get snapshots only in case a particular condition is satisfied: a periodic time interval ends or memory consumption increases by a specified value.

To start MyApp.exe and take snapshots periodically

  • Run the command: 

    dotMemory.exe start --trigger-timer=30s C:\MyApp\MyApp.exe MyAppArg1

Here:

  • --trigger-timer=30s- time period for taking snapshots (30 s in our case).

  • C:\MyApp\MyApp.exe- path to the executable file of the profiled app.

  • MyAppArg1- (optional) argument of MyApp.exe. Note that if application argument starts with the dash (-) character, you can escape it using double dash (--). For example, 

    dotMemory.exe start --trigger-timer=30s C:\MyApp\MyApp.exe -- -MyAppArg1

To start MyApp.exe and take snapshots when memory consumption increases by the specified value

  • Run the command: 

    dotMemory.exe start --trigger-mem-inc=50% --trigger-delay=5s C:\MyApp\MyApp.exe

Here:

  • --trigger-mem-inc=50%- a snapshot will be taken only when memory consumption of MyApp increases by 50%.

  • --trigger-delay=5s- a trigger will be enabled with the 5 s pause to skip the application startup phase.

Sometimes, you may want to get a snapshot immediately right after the start of the profiled application. For example, you can use this snapshot as a base for comparison.

To start MyApp.exe and take a snapshot right after the profiler is initialized

  • Run the command: 

    dotMemory.exe start --trigger-on-activation C:\MyApp\MyApp.exe

Here:

  • --trigger-on-activation- a snapshot will be taken immediately once the profiler is initialized. Note that if --trigger-delay is set, --trigger-on-activation will wait for this delay.

Starting application and getting snapshots using stdin messages

Sometimes it's necessary to have direct control over the profiling process, for example, get a snapshot at some exact moment by a direct command. This can be done by sending special messages to stdin of the command-line profiler.

warning

Messages sent to stdin must always start with a new line and end with a carriage return. Both stdin and stdout messages have a format of a JSON array.

To start MyApp.exe and control profiling using stdin messages

  1. No additional arguments are required. You can start profiling as usual using attach, or any of the start commands. For example: 

    dotMemory.exe start C:\MyApp\MyApp.exe

    dotMemory is able to inform you about how the profiling process is going by sending special service messages to stdout. This might be especially helpful in case you control profiling by some external script. To enable support for stdout messages, run dotMemory with the --service-output option, for example: 

    dotMemory.exe start --service-output C:\MyApp\MyApp.exe
    dotMemory sends the following messages to stdout:

    • Start of the profiling session 

      ##dotMemory["connected", {pid: 1234}]

    • Saving the snapshot 

      ##dotMemory["workspace-saved", {path: "..."}]

  2. Get a snapshot by sending the following command to stdin: 

    ##dotMemory["get-snapshot", {pid:1234}]
    If pid is specified, dotMemory will take a snapshot of the process with the specified PID. Otherwise, dotMemory will take snapshots of all profiled processes.

  3. To stop profiling and kill the profiled application, send the following command to stdin: 

    ##dotMemory["disconnect"]
    Works for all profiling sessions started with attach of any of the start commands.

Starting application and getting snapshots using API

You also have the option to control profiling (get snapshots, detach from process, and so on) using the API.

To start MyApp.exe and control profiling with API

  • Run the command: 

    dotMemory.exe start --use-api C:\MyApp\MyApp.exe

Attaching to and profiling running applications

If you want to profile an already running application and have full control over the profiling process (unlike the get-snapshot scenario), you should use the attach command. It lets the profiler to attach to running processes (by PID or name as well as get-snapshot) and get snapshots using triggers, stdin commands, or the API. For instance, here is the example of how to profile a running app MyApp and get snapshots using a trigger.

To attach to a running app and get snapshots periodically

  • Run the command: 

    dotMemory.exe attach MyApp.exe --trigger-timer=30s

(Windows only) Running and profiling IIS-hosted web applications

If you want to profile an ASP.NET web application that runs on IIS server, you should use the start-iis command. After you run the command, IIS will be started under profiling (for more details on how IIS-hosted apps are profiled, refer to Profile Web Application on IIS Server ). Note that start-iis supports the same ways of controlling profiling as the start command: using triggers, stdin commands, and the API. For instance, here is the example of how to profile a web app and get snapshots using a trigger.

To run IIS under profiling and get snapshots periodically

  • Run the command: 

    dotMemory.exe start-iis --trigger-timer=30s --open-url=localhost/myapp --use-browser=Chrome

Here:

  • --open-url=localhost/myapp- URL of the profiled application that will be opened after you run profiling.

  • --use-browser=Chrome- browser that should be used to open the URL. If not provided, the default system browser will be used.