dotMemory Unit

https://www.jetbrains.com/help/dotmemory-unit
Admin
dotMemory Unit is a framework that pairs with unit testing frameworks to detect memory issues like...
Tokens:19,736
Snippets:76
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install dotMemory Unit Package

Source: https://www.jetbrains.com/help/dotmemory-unit/Get_Started

Installs the latest stable build of the dotMemory Unit NuGet package into your test project. For EAP builds, use the '-pre' flag.

```powershell
PM> Install-Package JetBrains.DotMemoryUnit
```

--------------------------------

### dotMemoryUnit.exe Test Output Example

Source: https://www.jetbrains.com/help/dotmemory-unit/Using_dotMemory_Unit_Standalone_Runner

An example of the output from dotMemoryUnit.exe, showing test run statistics, including errors and failures.

```text
...\nTests run: 3, Errors: 1, Failures: 0, Inconclusive: 0, Time: 28.3051788194675 seconds\nNot run: 0, Invalid: 0, Ignored: 0, Skipped: 0\n\nErrors and Failures:\n1) Test Error : MainTests.IntegrationTests.Method2\nAssertTrafficException : Allocated memory amount\n\nExpected: 50,000,000\nBut was: 195,344,723\n...
```

--------------------------------

### Configure dotMemoryUnit Snapshot Saving

Source: https://www.jetbrains.com/help/dotmemory-unit/Get_Started

Demonstrates how to configure the behavior of dotMemory Unit regarding memory snapshot saving on test failures. The `DotMemoryUnit` attribute can be applied at method, class, or assembly levels to control this behavior, including disabling it or setting it to fail only when support is missing.

```C#
[DotMemoryUnit(FailIfRunWithoutSupport = false)]
```

--------------------------------

### Get dotMemory Unit Help

Source: https://www.jetbrains.com/help/dotmemory-unit/Using_dotMemory_Unit_Standalone_Runner

Displays help information for the dotMemoryUnit.exe command-line tool, detailing available parameters.

```bash
dotMemoryUnit.exe --help
```

--------------------------------

### Using dotMemory Unit with Unsupported Frameworks

Source: https://www.jetbrains.com/help/dotmemory-unit/Supported_Unit_Testing_Frameworks

Explains how to use dotMemory Unit with frameworks not explicitly listed. This involves using the `DotMemoryUnitController` class to define the start and end points of test methods.

```.NET
If the framework you use is not in this list, you still can use dotMemory Unit. All you need is to show dotMemory Unit where your test method starts and ends. This is done by the special `DotMemoryUnitController` class.
```

--------------------------------

### dotMemoryApi Methods

Source: https://www.jetbrains.com/help/dotmemory-unit/Alternative_Way_of_Working_with_Memory

Provides methods for memory analysis, including getting snapshots, comparing snapshots, retrieving memory traffic, and saving collected data.

```APIDOC
dotMemoryApi:
  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.
```

--------------------------------

### dotMemory Unit Test with MSTest Assertion

Source: https://www.jetbrains.com/help/dotmemory-unit/DMU_Introduction

This example demonstrates how to use dotMemory Unit with MSTest assertions. It performs the same memory check as the NUnit example but uses MSTest's syntax for asserting the count of 'Foo' objects.

```C#
Assert.AreEqual(0, memory.GetObjects(where => where.Type.Is<Foo>()).ObjectsCount);
```

--------------------------------

### dotMemory Unit Test with MSTest Assertion

Source: https://www.jetbrains.com/help/dotmemory-unit/index

This example demonstrates how to use dotMemory Unit with MSTest assertions. It performs the same memory check as the NUnit example but uses MSTest's syntax for asserting the count of 'Foo' objects.

```C#
Assert.AreEqual(0, memory.GetObjects(where => where.Type.Is<Foo>()).ObjectsCount);
```

--------------------------------

### Combine Traffic Queries with Logic Operators

Source: https://www.jetbrains.com/help/dotmemory-unit/Checking_Memory_Traffic

Illustrates how to combine multiple traffic queries using logical operators like '==' (equals), '&' (AND), and '|' (OR) for more complex filtering conditions. This example checks for objects of a specific type or implementing a specific interface.

```csharp
Assert.That(memory.GetTrafficFrom(memoryCheckPoint2).Where(obj => obj.Type == typeof(Foo) | obj.Interface == typeof(IEnumerable))
    .AllocatedMemory.ObjectsCount, Is.LessThan(10));
```

--------------------------------

### dotMemory Methods - JetBrains dotMemory Unit API

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Memory

Provides methods for creating memory checkpoints and performing memory analysis. The `Check` method can be used to get a reference to memory data or to perform assertions directly within a lambda expression.

```APIDOC
dotMemory static class:
  Check(): MemoryCheckPoint
    Returns an instance of the MemoryCheckPoint type which is a reference to memory data in the current execution point. Use this reference as a base for comparison with memory data taken in other points.

  Check(Action<Memory> check): MemoryCheckPoint
    Returns a reference to memory data in the current execution point and allows checking these data using Assert statements. The `check` Action is a lambda expression that should contain the assertions. The `Memory` instance passed to the lambda provides an interface for accessing the memory data. By default, if an assertion fails, dotMemory Unit will auto-save the workspace with all collected snapshots. Use this workspace to analyze why the test fails. Learn how to change the default auto-save behavior.
```

--------------------------------

### Run Tests with dotMemoryUnit.exe and dotnet CLI

Source: https://www.jetbrains.com/help/dotmemory-unit/Using_dotMemory_Unit_Standalone_Runner

Executes tests using the dotMemoryUnit.exe standalone launcher with the dotnet CLI. It specifies the path to the dotnet executable and the test command.

```bash
dotMemoryUnit.exe "c:\Program Files\dotnet\dotnet.exe" -- test "E:\MyProject\bin\Release\MainTests.dll"
```

--------------------------------

### Run NUnit Tests with dotMemoryUnit.exe

Source: https://www.jetbrains.com/help/dotmemory-unit/Using_dotMemory_Unit_Standalone_Runner

Executes NUnit tests using the dotMemoryUnit.exe standalone launcher. It specifies the path to the NUnit console runner and the test assembly.

```bash
dotMemoryUnit.exe "C:\NUnit 2.6.4\bin\nunit-console.exe" -- "E:\MyProject\bin\Release\MainTests.dll"
```

--------------------------------

### NamespaceProperty Methods for Object Selection

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Provides methods to create queries for selecting objects based on their namespace. Supports wildcard matching for namespace names.

```APIDOC
NamespaceProperty:
  Like(params string[] namespaceWildcard): Query
    - Creates a query to select objects belonging to specified namespaces using wildcard matching.
    - Parameters:
      - namespaceWildcard: An array of strings with namespace names, where '*' can be used as a wildcard.
    - Returns: A Query object for GetObjects.

  NotLike(params string[] namespaceWildcard): Query
    - Creates a query to select objects that do not belong to namespaces matching the specified patterns.
    - Parameters:
      - namespaceWildcard: An array of strings with namespace name patterns to exclude.
    - Returns: A Query object for GetObjects.
```

--------------------------------

### dotMemory Unit Support for Unsupported Frameworks

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Unsupported_Unit_Testing_Frameworks

Provides a way to integrate dotMemory Unit with unsupported unit testing frameworks by wrapping test methods with an IDisposable class that calls DotMemoryUnitController.TestStart() and DotMemoryUnitController.TestEnd().

```C#
internal class dotMemoryUnit : IDisposable
{
    [MethodImpl(MethodImplOptions.NoInlining)]
    private dotMemoryUnit()
    {
        // frame1 is DotMemoryUnit.Support() method; frame2 is "test" method
        DotMemoryUnitController.TestStart(new StackTrace().GetFrame(2).GetMethod());
    }

    [MethodImpl(MethodImplOptions.NoInlining)]
    public static IDisposable Support()
    {
        return new dotMemoryUnit();
    }

    public void Dispose()
    {
        DotMemoryUnitController.TestEnd();
    }
}


public class Tests
{
    [SomeTestAttribute]  // an attribute that specifies a test in the framework of your choice
    public void TestMethod1()
    {
        using (dotMemoryUnit.Support())
        {
            ... // your code goes here
        }
    }
}
```

--------------------------------

### AssertTraffic Attribute Usage

Source: https://www.jetbrains.com/help/dotmemory-unit/AssertTraffic_Attribute

This example demonstrates how to use the AssertTraffic attribute to assert that a test method allocates no more than 1000 strings. The attribute takes parameters like AllocatedObjectsCount and Types to specify the assertion criteria.

```C#
// Assert the test allocates no more than 1000 strings
[AssertTraffic(AllocatedObjectsCount = 1000, Types = new[] {typeof(string)})]
[Test]
public void TestMethod1()
{
    ...
}
```

--------------------------------

### InterfaceProperty Methods for Object Selection

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Provides methods to create queries for selecting objects based on the interfaces they implement. Supports single interface, multiple interfaces, and open generic interfaces.

```APIDOC
InterfaceProperty:
  Is(params Type[] typeList): Query
    - Creates a query to select objects implementing the specified interfaces.
    - Parameters:
      - typeList: An array of Type objects representing the interfaces to select.
    - Supports open generic interfaces.
    - Returns: A Query object for GetObjects.

  Is<T>: Query
    - Creates a query to select objects implementing a specific interface T.
    - Supports open generic interfaces.
    - Returns: A Query object for GetObjects.

  IsNot(params Type[] typeList): Query
    - Creates a query to select objects that do not implement the specified interfaces.
    - Parameters:
      - typeList: An array of Type objects representing the interfaces to exclude.
    - Supports open generic interfaces.
    - Returns: A Query object for GetObjects.

  IsNot<T>: Query
    - Creates a query to select objects that do not implement a specific interface T.
    - Supports open generic interfaces.
    - Returns: A Query object for GetObjects.

  Like(params string[] typeWildcard): Query
    - Creates a query to select objects by interface name using wildcard matching.
    - Parameters:
      - typeWildcard: An array of strings with interface names, where '*' can be used as a wildcard.
    - Returns: A Query object for GetObjects.

  NotLike(params string[] typeWildcard): Query
    - Creates a query to select objects that do not implement interfaces matching the specified name patterns.
    - Parameters:
      - typeWildcard: An array of strings with interface name patterns to exclude.
    - Returns: A Query object for GetObjects.
```

--------------------------------

### Supported Unit Testing Frameworks for dotMemory Unit

Source: https://www.jetbrains.com/help/dotmemory-unit/Supported_Unit_Testing_Frameworks

Details the unit testing frameworks that dotMemory Unit supports out-of-the-box, including MSTest, NUnit, and xUnit.net. It also mentions running tests via ReSharper or the standalone launcher.

```.NET
Supported unit testing frameworks:
  * MSTest
  * NUnit
  * xUnit.net
```

--------------------------------

### Snapshot Class Methods

Source: https://www.jetbrains.com/help/dotmemory-unit/Alternative_Way_of_Working_with_Memory

Methods for the Snapshot class to query and analyze memory data.

```APIDOC
Snapshot:
  GetObjects(Func<ObjectProperty, Query> query): 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>
    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.
```

--------------------------------

### AssertTraffic Attribute for Memory Traffic Analysis

Source: https://www.jetbrains.com/help/dotmemory-unit/Checking_Memory_Traffic

Demonstrates the usage of the AssertTraffic attribute to check memory traffic in C# unit tests. This attribute automatically starts collecting traffic data and allows filtering by allocated size and object types. Ensure memory allocation data collection is enabled for analysis.

```C#
[AssertTraffic(AllocatedSizeInBytes = 1000, Types = new[] { typeof(string) })] // starts collecting traffic data automatically
[Test]
public void TestMethod1()
{
    ... // Some user code
}
```

--------------------------------

### Taking Memory Checkpoints with dotMemory Unit

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Memory

Demonstrates how to initiate memory analysis by taking a memory checkpoint using the `dotMemory.Check` method. This method returns a `MemoryCheckPoint` instance that can be used for comparisons or traffic analysis. It also shows how to use a lambda expression with `dotMemory.Check` to filter memory data based on specific conditions.

```C#
using JetBrains.dotMemoryUnit;

// ... inside a test method ...

// Take a memory checkpoint
var checkpoint = dotMemory.Check();

// To prevent garbage collection of specific objects during a test:
// GC.KeepAlive(myObject);

// Take a memory checkpoint and filter memory data using a lambda
var checkpointWithFilter = dotMemory.Check(memory =>
{
    // Use the 'memory' instance to filter objects or traffic
    // For example, to get data about specific objects:
    // var specificObjects = memory.Objects.OfExactType<MyClass>();
    // Or to filter traffic:
    // var traffic = memory.NetworkTraffic.Where(t => t.Size > 1024);
});

// The 'checkpoint' and 'checkpointWithFilter' instances can be used for comparisons or traffic analysis.
```

--------------------------------

### Supported .NET Framework Versions for dotMemory Unit

Source: https://www.jetbrains.com/help/dotmemory-unit/Supported_Unit_Testing_Frameworks

Lists the .NET Framework and .NET Core versions supported by dotMemory Unit on Windows. This includes .NET Framework 3.5 to 4.7, .NET Core 2.0 to 3.1, and .NET 5.0, 6.0.

```.NET
Supported .NET Framework versions (on Windows only):
  * .NET Framework 3.5, 4.0, 4.5, 4.6 or 4.7
  * .NET Core 2.0, 3.0, 3.1
  * .NET 5.0, 6.0
```

--------------------------------

### TypeProperty Methods for Object Selection

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Provides methods to create queries for selecting objects by their type. Supports single type, multiple types, and open generic types. Wildcard matching is also available for type names.

```APIDOC
TypeProperty:
  Is(params Type[] typeList): Query
    - Creates a query to select all objects of the specified types.
    - Parameters:
      - typeList: An array of Type objects representing the types to select.
    - Supports open generic types.
    - Returns: A Query object for GetObjects.

  Is<T>: Query
    - Creates a query to select all objects of a specific type T.
    - Supports open generic types.
    - Returns: A Query object for GetObjects.

  IsNot(params Type[] typeList): Query
    - Creates a query to select all objects that do not belong to the specified types.
    - Parameters:
      - typeList: An array of Type objects representing the types to exclude.
    - Supports open generic types.
    - Returns: A Query object for GetObjects.

  IsNot<T>: Query
    - Creates a query to select all objects that do not belong to a specific type T.
    - Supports open generic types.
    - Returns: A Query object for GetObjects.

  Like(params string[] typeWildcard): Query
    - Creates a query to select objects by type name using wildcard matching.
    - Parameters:
      - typeWildcard: An array of strings with type names, where '*' can be used as a wildcard.
    - Returns: A Query object for GetObjects.

  NotLike(params string[] typeWildcard): Query
    - Creates a query to select objects that do not match the specified type name patterns.
    - Parameters:
      - typeWildcard: An array of strings with type name patterns to exclude.
    - Returns: A Query object for GetObjects.
```

--------------------------------

### Propagate Unit Test Runner Exit Code

Source: https://www.jetbrains.com/help/dotmemory-unit/Using_dotMemory_Unit_Standalone_Runner

Execute dotMemoryUnit.exe with the `--propagate-exit-code` argument to make it return the exit code of the specified unit test runner. Arguments for the target executable must be passed after `--`.

```bash
dotMemoryUnit.exe "C:\\NUnit 2.6.4\\bin\\nunit-console.exe" --propagate-exit-code -- "E:\\MyProject\\bin\\Release\\MainTests.dll"
```

--------------------------------

### JetBrains dotMemory Unit Memory Methods

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Memory

Provides methods for interacting with memory snapshots and object sets. Includes functionality to filter objects by query, group them by type, and compare memory states.

```C#
GetObjects(Func<ObjectProperty, Query> query): 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](https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets.html#ObjectProperty) object passed to the lambda allows selecting objects by type, interface, and other parameters. Returns an instance of the [ObjectSet](https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets.html#ObjectSet) type.

GroupByType: IReadOnlyCollection<TypeMemoryInfo>
  Returns a collection of objects of the [TypeMemoryInfo](https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets.html#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.

GetDifference(MemoryCheckPoint memoryCheckPoint): SnapshotDifference
  Gets difference between the current memory checkpoint and the checkpoint passed in the `memoryCheckPoint` parameter. Returns an instance of the [SnapshotDifference](https://www.jetbrains.com/help/dotmemory-unit/Reference_Comparing_Snapshots.html#SnapshotDifference) type that allows you to get data about new, dead, and survived objects.

GetTrafficFrom(MemoryCheckPoint memoryCheckPoint): Traffic
  Gets data about memory traffic in the time interval between the current memory snapshot and the snapshot passed in the `memoryCheckPoint` parameter. Returns an instance of the [Traffic](https://www.jetbrains.com/help/dotmemory-unit/Traffic_Class.html) type that allows you to get data about objects that were allocated and collected during the specified time interval.
```

--------------------------------

### dotMemory Unit API Reference

Source: https://www.jetbrains.com/help/dotmemory-unit/Reference

This section provides detailed information about dotMemory Unit types and functionalities. It covers working with memory, object sets, traffic, comparing snapshots, creating reusable queries, and integrating with unsupported unit testing frameworks.

```APIDOC
dotMemory Unit Reference:

Work with Memory:
  - Provides methods and types for analyzing memory usage and identifying memory leaks.
  - Details on how to capture and inspect memory snapshots.

Alternative Way to Work with Memory:
  - Explores an alternative approach to memory analysis within dotMemory Unit.

Configure dotMemory Unit:
  - Information on configuring dotMemory Unit settings and options.

Work with Object Sets:
  - Describes how to define, manage, and analyze object sets for targeted memory inspection.

Work with Traffic:
  - Details on capturing and analyzing network traffic data within the context of memory profiling.

Compare Snapshots:
  - Explains the process of comparing memory snapshots to identify changes and regressions.
  - Includes information on the `Reference_Comparing_Snapshots.html` page.

Create Reusable Queries:
  - Guides on creating and utilizing reusable queries for consistent memory analysis.

Work with Unsupported Unit Testing Frameworks:
  - Provides guidance on integrating dotMemory Unit with unit testing frameworks not natively supported.
```

--------------------------------

### dotMemoryApi Properties

Source: https://www.jetbrains.com/help/dotmemory-unit/Alternative_Way_of_Working_with_Memory

Properties to check the status of dotMemory Unit and control data collection.

```APIDOC
dotMemoryApi:
  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.
```

--------------------------------

### DotMemoryUnitController Methods for Unit Testing

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Unsupported_Unit_Testing_Frameworks

Provides methods to integrate dotMemory Unit with unsupported unit testing frameworks. These methods manage the lifecycle of a test and report failures, including specific handling for memory-related assertions.

```APIDOC
DotMemoryUnitController:
  TestStart(MethodBase testMethod)
    Indicates the start of a test.
    Parameters:
      testMethod: Specifies the test method that uses dotMemory Unit.

  TestEnd()
    Indicates the end of a test. This method must always be called, even if a test throws an exception.

  TestFailed(bool onMemoryAssert = true)
    Indicates test failure. Call this method when handling an exception in your test.
    Parameters:
      onMemoryAssert: Indicates whether the test failed on a 'memory' assertion or another reason. Defaults to true.
    Note: dotMemory.Check calls TestFailed(true) automatically on assertion failures.
```

--------------------------------

### ObjectProperty Methods for Query Creation

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Methods within the ObjectProperty class used to create specific queries for filtering objects. These queries can be passed to the GetObjects method.

```C#
Query LeakedOnEventHandler()
// Creates a query to select objects causing event handler leaks.

Query IsNotDominated()
// Creates a query to select objects not exclusively retained (retained by multiple objects).
```

--------------------------------

### AssemblyProperty Methods for Object Set Queries

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Provides methods to create queries for selecting objects based on their assemblies. These methods filter objects by including or excluding specific assemblies or patterns. They return a `Query` object usable with `GetObjects`.

```APIDOC
AssemblyProperty:
  Is(params Assembly[] assemblies): Query
    Creates the "Select all objects that belong to particular assemblies" query.
    Parameters:
      assemblies: An array of Assembly objects to include.
    Returns: A Query object for filtering.

  IsNot(params Assembly[] assemblies): Query
    Creates the "Select all objects that do not belong to particular assemblies" query.
    Parameters:
      assemblies: An array of Assembly objects to exclude.
    Returns: A Query object for filtering.

  Like(params string[] assemblyPattern): Query
    Creates the "Select all objects that belong to particular assemblies" query using patterns.
    Parameters:
      assemblyPattern: An array of string patterns for assembly names.
    Returns: A Query object for filtering.

  NotLike(params string[] assemblyPattern): Query
    Creates the "Select all objects that do not belong to particular assemblies" query using patterns.
    Parameters:
      assemblyPattern: An array of string patterns for assembly names to exclude.
    Returns: A Query object for filtering.
```

--------------------------------

### Compare Snapshots with dotMemory Unit

Source: https://www.jetbrains.com/help/dotmemory-unit/Comparing_Snapshots0

This C# code snippet demonstrates how to use dotMemory Unit to compare memory snapshots. It captures a checkpoint, executes code, and then asserts that a specific number of objects (in this case, zero survived objects from the 'MyApp' namespace) exist between the two checkpoints.

```C#
var memoryCheckPoint1 = dotMemory.Check();

foo.Bar();

dotMemory.Check(memory =>
{
    Assert.That(memory.GetDifference(memoryCheckPoint1)
        .GetSurvivedObjects(where => where.Namespace.Like("MyApp")).ObjectsCount, Is.EqualTo(0));
});
```

--------------------------------

### Comparing Memory Snapshots with dotMemory Unit

Source: https://www.jetbrains.com/help/dotmemory-unit/Reference_Comparing_Snapshots

This C# code snippet demonstrates how to use dotMemory Unit to compare two memory snapshots. It captures a first checkpoint, executes some user code, and then captures a second checkpoint to assert the number of new string objects created, helping to detect potential memory leaks or inefficient usage.

```C#
var memoryCheckPoint1 = dotMemory.Check();

foo.Bar();  // some user code

dotMemory.Check(memory =>
{
    // Compare two checkpoints
    Assert.That(memory.GetDifference(memoryCheckPoint1).GetNewObjects
        (where => where.Type.Is<string>()).ObjectsCount, Is.LessThan(10));
});
```

--------------------------------

### Filter Memory Traffic with Checkpoints

Source: https://www.jetbrains.com/help/dotmemory-unit/Checking_Memory_Traffic

Demonstrates how to use dotMemory.Check() to create checkpoints and analyze memory traffic between them. It shows how to filter traffic based on interfaces and object types, and count allocated objects within specific intervals.

```csharp
[DotMemoryUnit(CollectAllocations=true)] // collect traffic data
[Test]
public void TestMethod1()
{
    var memoryCheckPoint1 = dotMemory.Check();  // 1

    foo.Bar();

    var memoryCheckPoint2 = dotMemory.Check(memory =>
    {
        // 2
        Assert.That(memory.GetTrafficFrom(memoryCheckPoint1).Where(obj => obj.Interface.Is<IFoo>()).AllocatedMemory.SizeInBytes,
            Is.LessThan(1000));
    });

    bar.Foo();

    dotMemory.Check(memory =>
    {
        // 3
        Assert.That(memory.GetTrafficFrom(memoryCheckPoint2).Where(obj => obj.Type.Is<Bar>()).AllocatedMemory.ObjectsCount,
            Is.LessThan(10));
    });
}
```

--------------------------------

### SnapshotDifference Methods

Source: https://www.jetbrains.com/help/dotmemory-unit/Reference_Comparing_Snapshots

Provides methods to compare memory snapshots and retrieve sets of objects based on their lifecycle between two checkpoints. Supports optional queries for filtering results.

```APIDOC
SnapshotDifference:
  GetNewObjects(Func<ObjectProperty, Query> query): ObjectSet
    Gets a set of new objects created between memory checkpoints.
    Parameters:
      query (optional): A function to filter the resulting object set.
    Returns: An ObjectSet containing the new objects.

  GetDeadObjects(Func<ObjectProperty, Query> query): ObjectSet
    Gets a set of "dead" objects created before the base checkpoint and collected before the second checkpoint.
    Parameters:
      query (optional): A function to filter the resulting object set.
    Returns: An ObjectSet containing the dead objects.

  GetSurvivedObjects(Origin from = Origin.NewSnapshot): ObjectSet
    Gets a set of survived objects created before the base checkpoint and not collected before the second snapshot.
    Parameters:
      from: Specifies the source of data for survived objects (Origin.NewSnapshot or Origin.OldSnapshot).
    Returns: An ObjectSet containing the survived objects.
```

--------------------------------

### DotMemoryUnitAttribute Configuration

Source: https://www.jetbrains.com/help/dotmemory-unit/Configuring_dotMemory_Unit

Details the DotMemoryUnitAttribute used for configuring dotMemory Unit. This includes parameters for saving strategies and directory paths for workspaces.

```APIDOC
DotMemoryUnitAttribute:
  Applies to: Assembly, Test Class, Test Method
  Purpose: Configures dotMemory Unit settings.
  Parameters:
    SavingStrategy: Specifies when to save workspaces (e.g., OnCheckFail).
    Directory: Sets the directory path for saving workspaces.
```

--------------------------------

### Configure dotMemory Unit with DotMemoryUnitAttribute

Source: https://www.jetbrains.com/help/dotmemory-unit/Configuring_dotMemory_Unit

Demonstrates how to use the DotMemoryUnitAttribute to configure dotMemory Unit settings like SavingStrategy and Directory for a test method. This attribute can be applied at the assembly, test class, or test method level.

```C#
[DotMemoryUnit(SavingStrategy = SavingStrategy.OnCheckFail, Directory = @"C:\tmp\Method")]
[Test]
public void TestMethod1()
{
    ...
}
```

--------------------------------

### Using dotMemoryApi for Memory Assertions

Source: https://www.jetbrains.com/help/dotmemory-unit/Alternative_Way_of_Working_with_Memory

Demonstrates how to replace a standard `dotMemory.Check` assertion with direct calls to the `dotMemoryApi` class for checking object counts. This approach bypasses lambda expressions for more direct memory snapshot interaction.

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

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

--------------------------------

### Create and Use Reusable Query - C#

Source: https://www.jetbrains.com/help/dotmemory-unit/Creating_Reusable_Queries

Demonstrates how to create a reusable query using QueryBuilder to filter objects by generation and namespace, and then use this query within a dotMemory check to assert the object count.

```C#
var preset = QueryBuilder.GetObjects(where => where.Generation.Is(Generation.LOH))
    .GetObjects(where => where.Namespace.Like("MyNamespace*"));

dotMemory.Check(memory =>
{
    Assert.That(memory.GetObjects(preset).ObjectsCount, Is.EqualTo(0));
});
```

--------------------------------

### ObjectSet Properties

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Properties providing information about the ObjectSet, such as the total number of objects and their combined size in bytes.

```C#
int ObjectsCount
// Total number of objects in the set.

long SizeInBytes
// Total size of objects in the set in bytes.
```

--------------------------------

### TypeMemoryInfo Properties

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Details the properties available for TypeMemoryInfo, which provides information about the memory usage of a specific type.

```APIDOC
TypeMemoryInfo:
  ObjectsCount: int
    Description: Total number of objects of the Type.

  SizeInBytes: long
    Description: Total size of objects of the Type.

  TypeFullyQualifiedName: string
    Description: Fully qualified name of the Type.

  Type: Type
    Description: Type of objects represented by this instance of the TypeMemoryInfo class. Can be null in case the type is already unloaded or the type is in another AppDomain.
```

--------------------------------

### Object Set Queries with Logic Operators - dotMemory Unit

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

This C# code snippet shows an alternative syntax for object set queries in dotMemory Unit, using logic operators like '&' to combine conditions. It asserts that the count of string objects in the Large Object Heap (LOH) is zero.

```C#
Assert.That(memory.GetObjects(where => where.Type == (typeof(string)) &
    where.Generation == Generation.LOH).ObjectsCount, Is.EqualTo(0));
```

--------------------------------

### Filter objects by type and generation

Source: https://www.jetbrains.com/help/dotmemory-unit/Checking_for_Objects

Demonstrates filtering objects of a specific type (Foo) and generation (LOH) using chained GetObjects calls and checking the ObjectsCount.

```C#
Assert.That(memory.GetObjects(where => where.Type.Is<Foo>())
    .GetObjects(where => where.Generation.Is(Generation.LOH)).ObjectsCount, Is.EqualTo(0));
```

--------------------------------

### Enable Memory Allocation Data Collection in C#

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Traffic

Demonstrates how to enable memory allocation data collection for tests in dotMemory Unit. The `AssertTraffic` attribute automatically handles this for traffic analysis. For more complex scenarios without `AssertTraffic`, the `DotMemoryUnit` attribute with `CollectAllocations=true` should be applied.

```csharp
[DotMemoryUnit(CollectAllocations = true)]
public class MyTestClass
{
    // Your tests here
}
```

```csharp
[AssertTraffic]
public class MyTrafficTestClass
{
    // Your tests here
}
```

--------------------------------

### Traffic Class API Documentation

Source: https://www.jetbrains.com/help/dotmemory-unit/Traffic_Class

API reference for the Traffic class methods and properties in dotMemory Unit, detailing memory traffic data retrieval and manipulation.

```APIDOC
Traffic Class:
  Methods:
    Where(Func<TrafficProperty, Query> query): Traffic
      - Gets memory traffic data by a specific condition defined by a Query returned by a lambda expression.
      - The TrafficProperty instance passed to the lambda allows filtering traffic data by object type, interface, and other parameters.
      - Returns an instance of the Traffic type.
    Where(TrafficQuery predicate): Traffic
      - Gets memory traffic data by a specific condition defined by a reusable query (TrafficPredicateQuery).
      - Refer to QueryBuilder for more information.
      - Returns an instance of the Traffic type.
    GroupByType: IReadOnlyCollection<TypeTrafficInfo>
      - Returns a collection of TypeTrafficInfo objects, each representing traffic for a specific object type.
      - Each object contains info about allocated and collected objects of that type.
  Properties:
    AllocatedMemory: MemoryInfo
      - Data on allocated objects, including object count and total size.
    CollectedMemory: MemoryInfo
      - Data on collected objects, including object count and total size.
```

--------------------------------

### Asserting No Objects in LOH - dotMemory Unit

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

This C# code snippet demonstrates how to assert that there are no string or Foo objects in the Large Object Heap (LOH) using dotMemory Unit. It utilizes the `dotMemory.Check` method and chained `GetObjects` calls with type and generation filtering.

```C#
dotMemory.Check(memory =>
{
    Assert.That(memory.GetObjects(where => where.Type.Is(typeof(string), typeof(Foo)))
        .GetObjects(where => where.Generation.Is(Generation.LOH)).ObjectsCount, Is.EqualTo(0));
});
```

--------------------------------

### Filter objects by open generic interface

Source: https://www.jetbrains.com/help/dotmemory-unit/Checking_for_Objects

Illustrates how to select objects implementing an open generic interface (IGenericInterface<,>) using the Interface.Is() method.

```C#
public interface IGenericInterface<T1, T2> { }

...

dotMemory.Check(memory =>
    Assert.That(memory.GetObjects(where =>
        where.Interface.Is(typeof(IGenericInterface<,>))).ObjectsCount, Is.EqualTo(0)));
```

--------------------------------

### QueryBuilder Methods

Source: https://www.jetbrains.com/help/dotmemory-unit/Creating_Reusable_Queries

Provides methods for creating reusable queries to filter objects and memory traffic data. These methods accept lambda expressions to define query conditions.

```APIDOC
QueryBuilder:
  GetObjects(Func<ObjectProperty, Query> query): ObjectSetQuery
    Description: Creates a query that gets a subset of objects by a specific condition. The condition is defined by a Query that should be returned by a lambda expression. The ObjectProperty object passed to the lambda allows creating queries that select objects by type, interface, and other parameters.
    Parameters:
      query: A lambda expression defining the query condition using ObjectProperty.
    Returns: An instance of the ObjectSetQuery type.

  TrafficQuery(Func<TrafficProperty, Query> query): TrafficQuery
    Description: Creates a query that gets memory traffic data by a specific condition. The condition is defined by a Query that should be returned by a lambda expression. The TrafficProperty instance passed to the lambda allows creating queries that filter traffic data by object type, interface, and other parameters.
    Parameters:
      query: A lambda expression defining the query condition using TrafficProperty.
    Returns: An instance of the TrafficQuery type.
```

--------------------------------

### AssemblyProperty Class Overview

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

The AssemblyProperty class is used to create queries for selecting objects based on the assembly they belong to. Specific methods for filtering by assembly are not detailed in this section.

```APIDOC
AssemblyProperty:
  - Used to create "select objects by assembly" queries.
  - Further methods for filtering by assembly name or pattern are not specified in this documentation.
```

--------------------------------

### Traffic Class Usage

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Traffic

Illustrates how to use the Traffic class for more complex memory traffic assertions. This allows for checking traffic of specific object types within defined time intervals, providing more granular control and analysis.

```csharp
// Example of using Traffic class for complex assertions
var trafficInfo = Traffic.Collect(() => {
    // Code that allocates objects
});

// Assert traffic for a specific type within a time interval
Assert.That(trafficInfo.AllocatedObjects("System.String"), Is.LessThan(50));
```

--------------------------------

### Filter objects using logical operators

Source: https://www.jetbrains.com/help/dotmemory-unit/Checking_for_Objects

Shows an alternative syntax for object set queries using logical operators (==, &) to combine conditions for type and generation.

```C#
Assert.That(memory.GetObjects(where => where.Type == typeof(Foo) & where.Generation == Generation.LOH)
    .ObjectsCount, Is.EqualTo(0));
```

--------------------------------

### ObjectSet Methods

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Methods for manipulating and querying ObjectSet instances. These include filtering objects based on conditions, retrieving exclusively retained objects, and grouping objects by type.

```C#
ObjectSet GetObjects(Func<ObjectProperty, Query> query)
// Gets a subset of objects by a specific condition using a lambda expression.

ObjectSet GetObjects(ObjectSetQuery objectSetQuery)
// Gets a subset of objects by a specific condition using a reusable query.

ObjectSet GetExclusivelyRetainedObjects()
// Gets a set of objects that are exclusively retained by the current object set.

IReadOnlyCollection<TypeMemoryInfo> GroupByType
// Returns a collection of TypeMemoryInfo objects, each representing a type and its memory usage.
```

--------------------------------

### DotMemoryUnitAttribute Properties

Source: https://www.jetbrains.com/help/dotmemory-unit/Configuring_dotMemory_Unit

Defines properties for configuring dotMemory Unit behavior, such as memory allocation collection, workspace saving, and failure handling.

```APIDOC
DotMemoryUnitAttribute:
  CollectAllocations: bool
    Description: Defines whether memory allocation data (memory traffic and creation stack trace data) must be collected. Defaults to false. Collecting allocation data significantly increases profiling overhead. Use it only if you need to measure memory traffic. Note that the AssertTraffic attribute enables collecting allocations automatically.
    Default: false

  Directory: string
    Description: Path to the directory where workspace files must be saved. Can be a full path or a path relative to the assembly. Supports placeholders: <User>, <LocalAppData>, <CommonAppData>.

  DiskSpaceLimit: int
    Description: Maximum disk size in bytes for storing workspaces. Defaults to 200 MB. Checks total size of previously saved workspaces before saving.
    Default: 200 MB

  FailIfRunWithoutSupport: bool
    Description: If false, dotMemory.Check calls are ignored when run without dotMemory Unit support. If true, tests with dotMemory.Check calls will fail if run without support. Defaults to true.
    Default: true

  SavingStrategy: SavingStrategy enum
    Description: Defines conditions for auto-saving workspaces.
    Values:
      OnAnyFail: Auto-save workspace on any test failure.
      OnCheckFail: Auto-save workspace on dotMemory.Check call failure.
      Never: Do not auto-save workspaces.

  WorkspaceNumberLimit: int
    Description: Maximum number of workspaces that can be saved upon test failures. Defaults to 5.
    Default: 5
```

--------------------------------

### ObjectProperty Properties for Filtering

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Properties of the ObjectProperty class that allow selection of objects based on type, interface, namespace, assembly, and generation.

```C#
TypeProperty Type
// Allows selecting objects by type.

InterfaceProperty Interface
// Allows selecting objects by interface.

NamespaceProperty Namespace
// Allows selecting objects by namespace.

AssemblyProperty Assembly
// Allows selecting objects by assembly.

GenerationProperty Generation
// Allows selecting objects by generation.
```

--------------------------------

### dotMemory Unit Functionality

Source: https://www.jetbrains.com/help/dotmemory-unit/DMU_Introduction

dotMemory Unit provides several key functionalities for memory issue detection in unit tests. These include checking for specific object types in memory, monitoring memory traffic, calculating differences between memory snapshots, and saving snapshots for detailed analysis.

```C#
checking memory for objects of a certain type,
checking memory traffic,
getting the difference between memory snapshots,
saving memory snapshots for further investigation in [dotMemory](https://www.jetbrains.com/dotmemory/) (standalone .NET memory profiler).
```

--------------------------------

### Snapshot Properties

Source: https://www.jetbrains.com/help/dotmemory-unit/Alternative_Way_of_Working_with_Memory

Details the properties of a Snapshot object, including the total count and size of objects in memory. These properties are inherited from the base ObjectSet class.

```APIDOC
Snapshot Properties:

  ObjectsCount: int
    Description: Total number of objects in memory.
    Inherited from: ObjectSet

  SizeInBytes: long
    Description: Total size of objects in memory.
    Inherited from: ObjectSet
```

--------------------------------

### Combining Traffic Queries with Logic Operators in C#

Source: https://www.jetbrains.com/help/dotmemory-unit/Traffic_Class

Shows how to use logical operators (==, &, |) with dotMemory Unit's traffic queries for more complex filtering conditions.

```C#
Assert.That(memory.GetTrafficFrom(memoryCheckPoint2).Where(obj => obj.Type == typeof(Foo) | obj.Interface == typeof(IEnumerable))
    .AllocatedMemory.ObjectsCount, Is.LessThan(10));
```

--------------------------------

### Basic dotMemory Unit Test with NUnit

Source: https://www.jetbrains.com/help/dotmemory-unit/DMU_Introduction

This snippet shows a typical dotMemory Unit test using NUnit assertions. It checks for the absence of 'Foo' objects in memory, a common pattern for detecting memory leaks.

```C#
[Test]
public void TestMethod1()
{
... // do some work

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

--------------------------------

### AssertTraffic Attribute Usage

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Traffic

Demonstrates the basic usage of the AssertTraffic attribute to assert that memory traffic within a test does not exceed a specified value. This is useful for simple, direct checks on memory allocation.

```csharp
// Example of using AssertTraffic attribute
[AssertTraffic(MaxTraffic = 100)]
public void MyTestMethod() {
    // Test code that allocates objects
}
```

--------------------------------

### GenerationProperty Methods for Object Set Queries

Source: https://www.jetbrains.com/help/dotmemory-unit/Working_with_Object_Sets

Enables the creation of queries to select objects based on their managed heap segments (generations). These methods filter objects by including or excluding specific generations. They return a `Query` object usable with `GetObjects`.

```APIDOC
GenerationProperty:
  Is(params Generation[] generations): Query
    Creates the "Select all objects from particular managed heap segments" query.
    Parameters:
      generations: An array of Generation enum values representing heap segments to include.
    Returns: A Query object for filtering.

  IsNot(params Generation[] generations): Query
    Creates the "Select all objects that do not belong to particular managed heap segments" query.
    Parameters:
      generations: An array of Generation enum values representing heap segments to exclude.
    Returns: A Query object for filtering.
```
Tokens:
Raw