Alternative Way to Work with Memory

If you don't want to work with memory in a way described in Work with Memory, you have an alternative. We don't hide the "kernel" level of the framework which is based on the dotMemoryApi static class. This class allows you to directly work with memory snapshots without using lambdas. Actually, the dotMemory.Check method is a wrapper of dotMemoryApi calls.

You can use the dotMemoryApi class to write your own wrapper or directly work with memory snapshots.

In the latter case, you should keep in mind the following peculiarities:

Taking a snapshot may be a time-consuming operation.
Snapshots contain memory data on the moment you take them, not on the moment you access them.
In case of errors in the test code, test runner will be unable to distinguish whether the test fails because of a dotMemory Unit call or other test code.
All dotMemory Unit calls should be preceded by the check on whether support for dotMemory Unit is enabled.

For example, the following assertion

dotMemory.Check(memory =>
{
    Assert.That(memory.GetObjects(where => where.Type.Is<Foo>()).ObjectsCount, Is.EqualTo(0));
});

can be rewritten as

if (dotMemoryApi.IsEnabled)
{
    var snapshot1 = dotMemoryApi.GetSnapshot();

    Assert.That(snapshot1.GetObjects(where => where.Type.Is<Foo>()).ObjectsCount, Is.EqualTo(0));
}

dotMemoryApi static class

dotMemoryApi methods

Name	Description
`GetSnapshot(): Snapshot`	Returns a Snapshot instance which is a reference to memory data in the current execution point. Use this reference to get data about objects in memory, compare it with data from another snapshot, or get data about memory traffic between two snapshots.
`GetDifference(Snapshot snapshot1, Snapshot snapshot2): SnapshotDifference`	Gets difference between `snapshot1` and `snapshot2`. Returns an instance of the SnapshotDifference type that contains data about objects that were allocated and collected in the time interval between getting the snapshots.
`GetTrafficBetween(Snapshot snapshot1, Snapshot snapshot2): Traffic`	Gets data about memory traffic in the time interval between taking `snapshot1` and `snapshot2`. Returns an instance of the Traffic type that allows you to get data about objects that were allocated and collected during the specified time interval.
`SaveCollectedData(string directoryPath)`	Saves the workspace containing all memory snapshots collected during unit test run using the directory path specified by `directoryPath`. This can be either a full path or a path relative to the profiled assembly.

dotMemoryApi properties

Name	Type	Description
`IsEnabled`	`bool`	Returns `true` if a test is run under dotMemory Unit. Check this property before calling Assert statements.
`CollectAllocations`	`bool`	Defines whether the memory allocation data (memory traffic and creation stack trace data) must be collected. Set to `true` if you need the allocation data for your assertions. Note that this will significantly increase the profiling overhead.

Snapshot class

Represents memory data in some execution point.

Snapshot methods

Name	Description
`GetObjects(Func<ObjectProperty, Query> query): ObjectSet`	(Inherited from ObjectSet) Gets a subset of objects by a specific condition. The condition is defined by `query` in the form of a lambda expression. The ObjectProperty object passed to the lambda allows selecting objects by type, interface, and other parameters. Returns an instance of the ObjectSet type.
`GroupByType: IReadOnlyCollection<TypeMemoryInfo>`	(Inherited from ObjectSet) Returns a collection of objects of the TypeMemoryInfo type. Each object represents a particular type from the source object set and carries info about the number of objects of that type and their total size.

Name

Description

GetObjects(Func<ObjectProperty, Query> query): ObjectSet

(Inherited from ObjectSet)

Gets a subset of objects by a specific condition. The condition is defined by query in the form of a lambda expression. The ObjectProperty object passed to the lambda allows selecting objects by type, interface, and other parameters.

Returns an instance of the ObjectSet type.

GroupByType: IReadOnlyCollection<TypeMemoryInfo>

(Inherited from ObjectSet)

Returns a collection of objects of the TypeMemoryInfo type. Each object represents a particular type from the source object set and carries info about the number of objects of that type and their total size.

Snapshot properties

Name	Type	Description
`ObjectsCount`	`int`	(Inherited from ObjectSet) Total number of objects in memory.
`SizeInBytes`	`long`	(Inherited from ObjectSet) Total size of objects in memory.

Name

Type

Description

ObjectsCount

int

(Inherited from ObjectSet)

Total number of objects in memory.

SizeInBytes

long

(Inherited from ObjectSet)

Total size of objects in memory.

Last modified: 23 August 2023