Work with Object Sets

Object set is a number of objects selected by specific condition. To ease the understanding, think of an object set as of the result of some query, like "Select all objects of the string type promoted to Gen 2", or "Select all objects retained in memory by the instance A", and so on. An ObjectSet instance is returned as a result of the ObjectSet.GetObjects and ObjectSet.GetExclusivelyRetainedObjects methods.

To slice data by a number of conditions, you can build chains of GetObjects calls. The ObjectSet type has two properties that you can use in test assertions: ObjectsCount and SizeInBytes.

Example

For example, the following code asserts that there are no string and Foo objects in the Large Object Heap:

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));
});

dotMemory Unit also provides alternative syntax for object set queries. You can use the ==, &, and | logic operators to combine a number of queries. For example:

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

ObjectSet class

Represents a set of objects in memory.

ObjectSet methods

Name	Description
`GetObjects(Func<ObjectProperty, Query> query): ObjectSet`	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. Returns an instance of the `ObjectSet` type.
`GetObjects(ObjectSetQuery objectSetQuery): ObjectSet`	Gets a subset of objects by a specific condition. The condition is defined by a reusable query - an instance of the ObjectSetQuery type. For more information, refer to QueryBuilder. Returns an instance of the `ObjectSet` type.
`GetExclusivelyRetainedObjects(): ObjectSet`	Gets a set of objects that are exclusively retained (dominated) by the current object set. 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.

ObjectSet properties

Name	Type	Description
`ObjectsCount`	`int`	Total number of objects in the set.
`SizeInBytes`	`long`	Total size of objects in the set in bytes.

ObjectProperty class

Selects objects in a set by a specific condition: type, interface, and others.

ObjectProperty methods

Name	Description
`LeakedOnEventHandler(): Query`	Creates the "Select all objects that cause the event handlers leak" query. Learn more. Returns `Query` that can be used by the `GetObjects` method.
`IsNotDominated(): Query`	Creates the query "Select all objects that are not exclusively retained in memory (in other words, objects that are retained by more than one object)". Returns `Query` that can be used by the `GetObjects` method.

Name

Description

LeakedOnEventHandler(): Query

Creates the "Select all objects that cause the event handlers leak" query. Learn more.

Returns Query that can be used by the GetObjects method.

IsNotDominated(): Query

Creates the query "Select all objects that are not exclusively retained in memory (in other words, objects that are retained by more than one object)".

Returns Query that can be used by the GetObjects method.

ObjectProperty properties

Name	Type	Description
`Type`	`TypeProperty`	Allows selecting objects by type.
`Interface`	`InterfaceProperty`	Allows selecting objects by interface.
`Namespace`	`NamespaceProperty`	Allows selecting objects by namespace.
`Assembly`	`AssemblyProperty`	Allows selecting objects by assembly.
`Generation`	`GenerationProperty`	Allows selecting objects by generation.

TypeProperty class

TypeProperty is used to create "select objects by type" queries.

TypeProperty Methods

Name	Description
`Is(params Type[] typeList): Query`	Creates the "Select all objects of particular types" query. The list of types is passed in a `Type` array. Open generic types are also supported. Returns `Query` that can be used by the `GetObjects` method.
`Is<T>: Query`	Creates the "Select all objects of a particular type" query. Open generic types are also supported. Returns `Query` that can be used by the `GetObjects` method.
`IsNot(params Type[] typeList): Query`	Creates the "Select all objects that do not belong to particular types" query. The list of types is passed in a `Type` array. Open generic types are also supported. Returns `Query` that can be used by the `GetObjects` method.
`IsNot<T>: Query`	Creates the "Select all objects that do not belong to a particular type" query. Open generic types are also supported. Returns `Query` that can be used by the `GetObjects` method.
`Like(params string[] typeWildcard): Query`	Creates the "Select all objects of particular types" query. The list of types is passed in a `string` array. Asterisk (*) wildcards are allowed. Returns `Query` that can be used by the `GetObjects` method.
`NotLike(params string[] typeWildcard): Query`	Creates the "Select all objects that do not belong to particular types" query. The list of types is passed in a `string` array. Asterisk (*) wildcards are allowed. Returns `Query` that can be used by the `GetObjects` method.

InterfaceProperty class

InterfaceProperty is used to create "select objects by interface" queries.

InterfaceProperty Methods

Name	Description
`Is(params Type[] typeList): Query`	Creates the "Select all objects that implement particular interfaces" query. The list of interfaces is passed in a `Type` array. Open generic interfaces are also supported. Returns `Query` that can be used by the `GetObjects` method.
`Is<T>: Query`	Creates the "Select all objects that implement a particular interface" query. Open generic interfaces are also supported. Returns `Query` that can be used by the `GetObjects` method.
`IsNot(params Type[] typeList): Query`	Creates the "Select all objects that do not implement particular interfaces" query. The list of interfaces is passed in a `Type` array. Open generic interfaces are also supported. Returns `Query` that can be used by the `GetObjects` method.
`IsNot<T>: Query`	Creates the "Select all objects that do not implement a particular interface" query. Open generic interfaces are also supported. Returns `Query` that can be used by the `GetObjects` method.
`Like(params string[] typeWildcard): Query`	Creates the "Select all objects that implement particular interfaces" query. The list of interfaces is passed in a `string` array. Asterisk (*) wildcards are allowed. Returns `Query` that can be used by the `GetObjects` method.
`NotLike(params string[] typeWildcard): Query`	Creates the "Select all objects that implement particular interfaces" query. The list of interfaces is passed in a `string` array. Asterisk (*) wildcards are allowed. Returns `Query` that can be used by the `GetObjects` method.

NamespaceProperty class

NamespaceProperty is used to create "select objects by namespace" queries.

NamespaceProperty methods

Name	Description
`Like(params string[] namespaceWildcard): Query`	Creates the "Select all objects that belong to particular namespaces" query. The list of namespaces is passed in a `string` array. Asterisk (*) wildcards are allowed. Returns `Query` that can be used by the `GetObjects` method.
`NotLike(params string[] namespaceWildcard): Query`	Creates the "Select all objects that do not belong to particular namespaces" query. The list of namespaces is passed in a `string` array. Asterisk (*) wildcards are allowed. Returns `Query` that can be used by the `GetObjects` method.

Name

Description

Like(params string[] namespaceWildcard): Query

Creates the "Select all objects that belong to particular namespaces" query. The list of namespaces is passed in a string array. Asterisk (*) wildcards are allowed.

Returns Query that can be used by the GetObjects method.

NotLike(params string[] namespaceWildcard): Query

Creates the "Select all objects that do not belong to particular namespaces" query. The list of namespaces is passed in a string array. Asterisk (*) wildcards are allowed.

Returns Query that can be used by the GetObjects method.

AssemblyProperty class

AssemblyProperty is used to create "select objects by assembly" queries.

AssemblyProperty methods

Name	Description
`Is(params Assembly[] assemblies): Query`	Creates the "Select all objects that belong to particular assemblies" query. The list of assemblies is passed in a `Assembly` array. Returns `Query` that can be used by the `GetObjects` method.
`IsNot(params Assembly[] assemblies): Query`	Creates the "Select all objects that do not belong to particular assemblies" query. The list of assemblies is passed in a `Assembly` array. Returns `Query` that can be used by the `GetObjects` method.
`Like(params string[] assemblyPattern): Query`	Creates the "Select all objects that belong to particular assemblies" query. The list of assemblies is passed in a `string` array. Returns `Query` that can be used by the `GetObjects` method.
`NotLike(params string[] assemblyPattern): Query`	Creates the "Select all objects that do not belong to particular assemblies" query. The list of assemblies is passed in a `string` array. Returns `Query` that can be used by the `GetObjects` method.

GenerationProperty class

GenerationProperty is used to create "select objects by generation" queries.

GenerationProperty methods

Name	Description
`Is(params Generation[] generations): Query`	Creates the "Select all objects from particular managed heap segments" query. The list of heap segments is passed in a `Generation` array. Returns `Query` that can be used by the `GetObjects` method.
`IsNot(params Generation[] generations): Query`	Creates the "Select all objects that do not belong to particular managed heap segments" query. The list of heap segments is passed in a `Generation` array. Returns `Query` that can be used by the `GetObjects` method.

Name

Description

Is(params Generation[] generations): Query

Creates the "Select all objects from particular managed heap segments" query. The list of heap segments is passed in a Generation array.

Returns Query that can be used by the GetObjects method.

IsNot(params Generation[] generations): Query

Creates the "Select all objects that do not belong to particular managed heap segments" query. The list of heap segments is passed in a Generation array.

Returns Query that can be used by the GetObjects method.

Generation enum

Represents certain managed heap segments:

Value	Description
`Gen1`	Generation 1 heap segment.
`Gen2`	Generation 2 heap segment.
`LOH`	Large object heap.

TypeMemoryInfo class

TypeMemoryInfo carries info about a group of objects of the same type: a number of objects, and their size. Instances of the TypeMemoryInfo class are a result of objects grouping via the GroupByType() method.

TypeMemoryInfo properties

Name	Type	Description
`ObjectsCount`	`int`	Total number of objects of the `Type`.
`SizeInBytes`	`long`	Total size of objects of the `Type`.
`TypeFullyQualifiedName`	`string`	Fully qualified name of the `Type`.
`Type`	`Type`	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.

Last modified: 05 September 2023