dotMemory 2021.1 Help

API Reference

The profiling API

MemoryProfiler class methods

ItemReturnsDescription
GetFeatures()enum MemoryFeatures: uint

Returns a set of features currently active in the profiler: Bit flags in the MemoryFeatures value fully describe the current profiler state. Each bit indicates whether a corresponding feature is currently available:

  • Ready = 0x1: Indicates whether the profiler is ready to work. You need to check this flag only in case you attach the profiler to the current process: the flag will be set once the profiler is ready to accept your commands. If you start a process under profiling, this flag is always set. After you detach the profiler from the process, the flag is cleared.

  • Detach = 0x2: Indicates whether it is possible to use MemoryProfiler.Detach().
    0: the profiler will ignore MemoryProfiler.Detach().
    1: MemoryProfiler.Detach() will detach the profiler from the profiled process.

  • CollectAllocations = 0x4: Indicates whether it is possible to use CollectAllocations(bool enabled). If 0, the profiler ignores the CollectAllocations call. If 1, the CollectAllocations call will take effect.

GetSnapshot()Collect memory snapshot and save it to the disk. This method forces full garbage collection.
Doesn't throw any errors even if the application is run with profiling disabled.
GetSnapshot(string name)[Internal use only]
Collect memory snapshot and save it to the disk. This method forces full garbage collection.
Doesn't throw any errors even if the application is run with profiling disabled.
name is the name of the memory snapshot. It is not a filename.
ForceGc()Forces full garbage collection.
Doesn't throw any errors even if the application is run with profiling disabled.
CollectAllocations(bool enable)Enable/disable collecting memory allocation data. Does nothing if collecting allocation data is disabled in the profiler. To check whether the collecting is enabled, use MemoryProfiler.GetFeatures().
Doesn't throw any errors even if the application is run with profiling disabled.
Detach()Detach the profiler from the profiled process. Does nothing if detaching is disabled in the profiler. To check whether the detaching is enabled, use MemoryProfiler.GetFeatures() with MemoryFeatures.Detach flag. Doesn't throw any errors even if the application is run with profiling disabled.

The self-profiling API

DotMemory class methods

ItemReturnsDescription
EnsurePrerequisite(Uri nugetUrl = null, NuGetApi nugetApi = NuGetApi.V3, string downloadTo = null)Initializes the profiler. This method is a simplified way to call the EnsurePrerequisiteAsync() method. This is the recommended method for profiler initialization.
EnsurePrerequisiteAsync(CancellationToken cancellationToken, IProgress<double> progress = null, Uri nugetUrl = null, NuGetApi nugetApi = NuGetApi.V3, string downloadTo = null)Task(We recommend that you use EnsurePrerequisite() instead)
Initializes the profiler. It is a simplified overload of the EnsurePrerequisiteAsync() method.
EnsurePrerequisiteAsync( CancellationToken cancellationToken, IProgress<double> progress = null, Uri nugetUrl = null, NuGetApi nugetApi = NuGetApi.V3, string downloadTo = null)Task(We recommend that you use EnsurePrerequisite() instead)
Initializes the profiler. During the initialization, the API checks whether the dotMemory.exe console profiler exists in the same folder with the executing assembly. If the console profiler is not found, downloads the compatible JetBrains.dotMemory.Console NuGet-package into the downloadTo folder. The compatible package version is set by the NupkgVersion constant. You can track the download progress using the progress callback variable and cancel the downloading using cancellationToken.
GetSnapshotOnce()Gets a memory snapshot using the default profiling configuration.
GetSnapshotOnce(DotMemory.Config config)StringGets a memory snapshot using the specified profiling config. Returns a string with the path to the saved snapshot (dotMemory workspace).
Attach()Attaches dotMemory to the current process using the default profiling configuration.
Attach(DotMemory.Config config)Attaches dotMemory to the current process using the specified profiling config.
Detach()StringDetaches dotMemory from the current process. Returns a string with the path to the saved snapshot (dotMemory workspace).
GetSnapshot(string name = null)StringGets a memory snapshot. name is the name of the snapshot.

DotMemory.Config class methods

ItemReturnsDescription
UseLogLevelTrace()DotMemory.ConfigSpecifies TRACE log level.
UseLogLevelVerbose()DotMemory.ConfigSpecifies VERBOSE log level.
UseLogFile(string filePath)DotMemory.ConfigSpecifies the path to the log file.
SaveToFile(string filePath, bool overwrite = false)DotMemory.ConfigSpecifies the path to the workspace file (snapshots storage).
SaveToDir(string dirPath)DotMemory.ConfigSpecifies the path to the workspace directory (filename will be auto-generated). SaveToDir and SaveToFile are mutually exclusive.
OpenDotMemory()DotMemory.ConfigSpecifies whether to open the generated workspace in JetBrains dotMemory.
WithCommandLineArgument(string argument)DotMemory.ConfigAppends an arbitrary argument to the command line as is (without any quoting, and so on).
UseApi()DotMemory.Config(Advanced use only)
Specifies whether to use JetBrains.Profiler.Api to control the profiling session. UseApi() and DoNotUseApi() are mutually exclusive. Note that UseAPI will take no effect if you take a snapshot using GetSnapshotOnce().
DoNotUseApi()DotMemory.Config(Advanced use only)
Prohibits using JetBrains.Profiler.Api to control the profiling session. Session is controlled only by using dotMemory.exe. UseApi() and DoNotUseApi() are mutually exclusive.
Last modified: 08 March 2021