How-To's

dotMemory Command Line Tools

In the 2017.1 release, dotMemory introduced a console profiler. Now, using the dotMemory.exe tool, you can perform memory profiling from the command line. Why would you? The short answer would be to automate the process of gathering memory snapshots. There are lots of possible use cases:

  • You want to speed up profiling routines, e.g. when you regularly profile the same application and do not want to start the dotMemory user interface each time.
  • You need to profile your application on someone’s computer you don’t have access to (e.g., your client’s) but don’t want to bother him with dotMemory installation and detailed profiling instructions.
  • Or maybe you want to include memory profiling into your continuous integration builds (though our dotMemory Unit framework could be much handier for this purpose).

Where can I get it?

dotMemory.exe is distributed separately from dotMemory. You can download the tool on the dotMemory download page. Note that dotMemory.exe is free and does not require you to have the full dotMemory installed.

Now let’s take a look at the most common usage scenarios.

Instantly get a snapshot

The most popular scenario is probably getting a snapshot of an already running application.

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

1234 here is the process ID. Right after you run the command, dotMemory will attach to the process, take a snapshot, save it to C:\Snapshots, and detach from the process.
You can also specify the profiled application with its process name:

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

or

dotMemory.exe get-snapshot MyApp --all

--all and --with-max-mem options let you avoid ambiguity when multiple processes with the same name are running:

  • --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 processes (snapshot per process).

Get snapshots by condition

Sometimes you may need 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 (in the example, it’s 30 s):

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

  • or memory consumption increases by a specified value (50% in the example below):

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

    (--trigger-delay=5s here stands for the 5s delay required to skip application startup phase)

Note that in both examples, we use the start command to start the application. If you want to profile a ASP.NET application, you should use the start-iis command. In this case, IIS and all its application pools will be started under profiling. E.g.:

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

What if the app you want to profile is already running but you still want to use triggers? Simply use the attach command:

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

Get snapshots using stdin messages

If you want to take direct control over the profiling process (i.e., get snapshots at some exact moment), you can do this by sending messages to stdin of dotMemory.exe:

  • Get a snapshot:

    ##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.

  • Stop profiling and kill the profiled application:

    ##dotMemory["disconnect"]

These stdin messages work for all profiling sessions started with start, start-iis, or attach commands.

Moreover, if you want to write a profiling script, you may find it useful that dotMemory.exe is able to send service messages to stdout:

  • Start of the profiling session:

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

  • Saving the snapshot:

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

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

Get snapshots using API

Of course, we don’t forget about our profiling API. If you control profiling directly from your code using the dotMemory API, run dotMemory.exe with the -–use-api command. E.g.:

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

We hope you’ll find the dotMemory console profiler useful and helpful in automating your profiling routines. As usual, we invite you to download the tool, try it on your own and share your experience.

image description