DkmDataContainer Class

  • Reference

Definition

Namespace:
Microsoft.VisualStudio.Debugger
Assembly:
Microsoft.VisualStudio.Debugger.Engine.dll

DkmDataContainer is a building block which is used throughout this API. It allows many of the objects in this API to contain 'virtual fields' which are added by any component in the system. This is similar to a type-safe version of the 'expando' concept in JScript.

Rules for DkmDataContainer:

  1. All the 'reference' objects in the system inherit from DkmDataContainer. Reference objects are tracked by the dispatcher component of this system, and at various marshalling points (managed->native, native->managed, remoting) the object reference identity is preserved. 'Value' objects do not inherit from DkmDataContainer because the system does not track these objects, so at any marshalling transition, the value of the object is copied.
  2. The 'virtual fields' of these objects which inherit from DkmDataContainer are called data items.
  3. Data items are PRIVATE to the component that added them. This feature cannot be used to share fields across component boundaries.
  4. Data items are instances of a data item class. In managed code, data item classes inherit from DkmDataItem to identify them as a data item. In native code, data items inherit from IUnknown.
  5. Usually, a component would never need to remove a data item. This is because data items are automatically removed when the container object is closed.
public ref class DkmDataContainer abstract : MarshalByRefObject
public abstract class DkmDataContainer : MarshalByRefObject
type DkmDataContainer = class
    inherit MarshalByRefObject
Public MustInherit Class DkmDataContainer
Inherits MarshalByRefObject
Inheritance
MarshalByRefObject
DkmDataContainer
Derived

Examples

// Example data item class. In managed code, data items need to inherit from DkmDataItem class AliasLog : DkmDataItem { readonly string LogPath; readonly StreamWriter Writer;

public AliasLog(string log)
{
    LogPath = log;
    Writer = new StreamWriter(log);
}

// Data items can override the 'OnClose' method to receive notification when the data
// container object (DkmClrAlias in our example) is closed.
protected override void OnClose()
{
    Writer.Close();
}

}

// Create a new instance of the example data item class AliasLog log = new AliasLog("c:\foo.log");

// data items can be passed to a create method... DkmClrAlias alias = DkmClrAlias.Create("ExampleName", log);

// ...or then can be added using SetDataItem alias.SetDataItem<AliasLog>(DkmDataCreationDisposition.CreateAlways, log);

// then the value can be retrieved using GetDataItem AliasLog find = alias.GetDataItem<AliasLog>();

Properties

IsUnloaded

Returns true if a 'unloaded' event has been raised for this object (example: DkmThread::Unload is called) or if the object has been closed. Note that care must be used when checking this status as, without synchronization, the returned status may no longer be accurate the instruction after it is read.

Methods

GetDataItem<T>()

Gets the instance of 'T' which has been added to this container instance. If this container does not contain a 'T', this function will return null.
RemoveDataItem<T>()

Remove the instance of 'T' from this container. It is usually unnecessary to call this method as a data container will automatically be emptied when the object is closed.
SetDataItem<T>(DkmDataCreationDisposition, T)

Place a new item in the data container.

Applies to