Native Debugger Objects in JavaScript Extensions - Debugger Object Details
This topic describes additional details about using the native debugger objects in JavaScript extensions.
Native debugger objects represent various constructs and behaviors of the debugger environment. The objects can be passed into (or acquired in) JavaScript extensions to manipulate the state of the debugger.
For information about Debugger object JavaScript extensions, see Native Debugger Objects in JavaScript Extensions.
For general information about working with JavaScript, see JavaScript Debugger Scripting.
For example JavaScript scripts and extensions, the debugger team hosts a GitHub repo at https://github.com/Microsoft/WinDbg-Samples.
Debugger Objects in JavaScript Extensions
Passing Native Objects
Debugger objects can be passed into or acquired in JavaScript extensions in a variety of ways.
- They can be passed to JavaScript functions or methods
- They can be the instance object for a JavaScript prototype (as a visualizer, for instance)
- They can be returned from host methods designed to create native debugger objects
- They can be returned from host methods designed to create debugger native objects
Debugger objects that are passed to a JavaScript extension have a set of functionality that is described in this section.
- Property Access
- Projected Names
- Special Types Pertaining to Native Debugger Objects
- Additional Attributes
Property Access
While there are some properties on objects which are placed there by the JavaScript provider itself, the majority of properties on a native object which enters JavaScript are provided by the data model. This means that for a property access --- object.propertyName or object[propertyName], the following will occur.
- If propertyName is the name of a property projected onto the object by the JavaScript provider itself, it will resolve to this first; otherwise
- If propertyName is the name of a key projected onto the object by the data model (another Visualizer), it will resolve to this name second; otherwise
- If propertyName is the name of a field of the native object, it will resolve to this name third; otherwise
- If object is a pointer, the pointer will be dereferenced, and the cycle above will continue (a projected property of the dereferenced object followed by a key followed by a native field)
The normal means of property access in JavaScript -- object.propertyName and object[propertyName] -- will access the underlying native fields of an object, much as the 'dx' command would within the debugger.
Projected Names
The following properties (and methods) are projected onto native objects which enter JavaScript.
| Method | Signature | Description |
|---|---|---|
| hostContext | Property | Returns an object which represents the context the object is within (the address space, debug target, etc...) |
| targetLocation | Property | Returns an object which is an abstraction of where the object is within an address space (virtual address, register, sub-register, etc...) |
| targetSize | Property | Returns the size of the object (effectively: sizeof(<TYPE OF OBJECT>) |
| addParentModel | .addParentModel(object) | Adds a new parent model (akin to a JavaScript prototype but on the data model side) to the object |
| removeParentModel | .removeParentModel(object) | Removes a given parent model from the object |
| runtimeTypedObject | Property | Performs analysis on the object and tries to convert it to the runtime (most derived) type |
| targetType | Property | JavaScript extensions have direct access to the type system of the underlying language. This access is expressed through the notion of type objects. For more information, see Native Debugger Objects in JavaScript Extensions - Type Objects |
If the object is a pointer, the following properties (and methods) are projected onto the pointer which enters JavaScript:
| Property Name | Signature | Description |
|---|---|---|
| add | .add(value) | Performs pointer math addition between the pointer and the specified value |
| address | Property | Returns the address of the pointer as a 64-bit ordinal object (a library type) |
| dereference | .dereference() | Dereferences the pointer and returns the underlying object |
| isNull | Property | Returns whether or not the pointer value is nullptr (0) |
Special Types Pertaining to Native Debugger Objects
Location Objects
The location object which is returned from the targetLocation property of a native object contains the following properties (and methods).
| Property Name | Signature | Description |
|---|---|---|
| add | .add(value) | Adds an absolute byte offset to the location. |
| subtract | .subtract(value) | Subtracts an absolute byte offset from the location. |
Additional Attributes
Iterability
Any object which is understood as iterable by the data model (it is a native array or it has a visualizer (NatVis or otherwise) which makes it iterable) will have an iterator function (indexed via the ES6 standard Symbol.iterator) placed upon it. This means that you can iterate a native object in JavaScript as follows.
function iterateNative(nativeObject)
{
for (var val of nativeObject)
{
//
// val will contain each element iterated from the native object. This would be each element of an array,
// each element of an STL structure which is made iterable through NatVis, each element of a data structure
// which has a JavaScript iterator accessible via [Symbol.iterator], or each element of something
// which is made iterable via support of IIterableConcept in C/C++.
//
}
}
Indexability
Objects which are understood as indexable in one dimension via ordinals (e.g.: native arrays) will be indexable in JavaScript via the standard property access operator -- object[index]. If an object is indexable by name or is indexable in more than one dimension, the getValueAt and setValueAt methods will be projected onto the object so that JavaScript code can utilize the indexer.
function indexNative(nativeArray)
{
var first = nativeArray[0];
}
String Conversion
Any native object which has a display string conversion via support of IStringDisplayableConcept or a NatVis DisplayString element will have that string conversion accessible via the standard JavaScript toString method.
function stringifyNative(nativeObject)
{
var myString = nativeObject.toString();
}
Creating Native Debugger Objects
As mentioned, a JavaScript script can get access to native objects by having them passed into JavaScript in one of several ways or it can create them through calls to the host library. Use the following functions to create native debugger objects.
| Method | Signature | Description |
|---|---|---|
host.getModuleSymbol |
getModuleSymbol(moduleName, symbolName, [contextInheritor]) getModuleSymbol(moduleName, symbolName, [typeName], [contextInheritor]) |
Returns an object for a global symbol within a particular module. The module name and symbol name are strings. If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off test script should always supply an explicit context. If the optional typeName argument is supplied, the symbol will be assumed to be of the passed type and the type indicated in symbol(s) will be ignored. Note that any caller which expects to operate on public symbols for a module should always supply an explicit type name. |
host.getModuleContainingSymbol |
getModuleContainingSymbol(location, [contextInheritor]) | Returns the symbol (e.g.: function or data) which contains the given address. Note that this will only work if there are private symbols for the module containing the given address. If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off test script should always supply an explicit context. |
host.createPointerObject |
createPointerObject(address, moduleName, typeName, [contextInheritor]) |
Creates a pointer object at the specified address or location. The module name and type name are strings. If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off test script should always supply an explicit context. |
host.createTypedObject |
createTypedObject(location, moduleName, typeName, [contextInheritor]) |
Creates a object which represents a native typed object within the address space of a debug target at the specified location. The module name and type name are strings. If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off test script should always supply an explicit context. |
Host APIs for JavaScript Extensions
The JavaScript provider inserts an object called host into the global namespace of every script which it loads. This object provides access to critical functionality for the script as well as access to the namespace of the debugger. It is set up in two phases.
Phase 1: Before any script executes, the host object only contains the minimal set of functionality necessary for a script to initialize itself and register its extensibility points (both as producer and consumer). The root and initialization code is not intended to manipulate the state of a debug target or perform complex operations and, as such, the host is not fully populated until after the initializeScript method returns.
Phase 2: After initializeScript returns, the host object is populated with everything necessary to manipulate the state of debug targets.
Host Object Level
A few key pieces of functionality are directly under the host object. The remainder are sub-namespaced. Namespaces include the following.
| Namespace | Description |
|---|---|
| diagnostics | Functionality to assist in the diagnosis and debugging of script code |
| memory | Functionality to enable memory reading and writing within a debug target |
Root Level
Directly within the host object, the following properties, methods, and constructors can be found.
| Name | Signature | Phase Present | Description |
|---|---|---|---|
| createPointerObject | createPointerObject(address, moduleName, typeName, [contextInheritor]) |
2 | Creates a pointer object at the specified address or location. The module name and type name are strings. The optional contextInheritor argument works as with getModuleSymbol. |
| createTypedObject | createTypedObject(location, moduleName, typeName, [contextInheritor]) |
2 | Creates a object which represents a native typed object within the address space of a debug target at the specified location. The module name and type name are strings. The optional contextInheritor argument works as with getModuleSymbol. |
| currentProcess | Property |
2 | Returns the object representing the current process of the debugger |
| currentSession | Property |
2 | Returns the object representing the current session of the debugger (which target, dump, etc...) is being debugged |
| currentThread | Property |
2 | Returns the object representing the current thread of the debugger |
| evaluateExpression | evaluateExpression(expression, [contextInheritor]) |
2 | This calls into the debug host to evaluate an expression using the language of the debug target only. If the optional contextInheritor argument is supplied, the expression will be evaluated in the context (e.g.: address space and debug target) of the argument; otherwise, it will be evaluated in the current context of the debugger |
| evaluateExpressionInContext | evaluateExpressionInContext(context, expression) |
2 | This calls into the debug host to evaluate an expression using the language of the debug target only. The context argument indicates the implicit this pointer to utilize for the evaluation. The expression will be evaluated in the context (e.g.: address space and debug target) indicated by the context argument. |
| getModuleSymbol | getModuleSymbol(moduleName, symbolName, [contextInheritor]) |
2 | Returns an object for a global symbol within a particular module. The module name and symbol name are strings. If the optional contextInheritor argument is supplied, the module and symbol will be looked up within the same context (address space, debug target) as the passed object. If the argument is not supplied, the module and symbol will be looked up in the debugger's current context. A JavaScript extension which is not a one-off script should always supply an explicit context |
| getNamedModel | getNamedModel(modelName) |
2 | Returns the data model which was registered against a given name. Note that it is perfectly legal to call this against a name which is not yet registered. Doing so will create a stub for that name and manipulations of the stub will be made to the actual object upon registration |
| indexedValue | new indexedValue(value, indicies) |
2 | A constructor for an object which can be returned from a JavaScript iterator in order to assign a default set of indicies to the iterated value. The set of indicies must be expressed as a JavaScript array. |
| Int64 | new Int64(value, [highValue]) |
1 | This constructs a library Int64 type. The single argument version will take any value which can pack into an Int64 (without conversion) and place it into such. If an optional second argument is supplied, a conversion of the first argument is packed into the lower 32-bits and a conversion of the second argument is packed into the upper 32 bits. |
| namedModelParent | new namedModelParent(object, name) |
1 | A constructor for an object intended to be placed in the array returned from initializeScript, this represents using a JavaScript prototype or ES6 class as a data model parent extension of a data model with the given name |
| namedModelRegistration | new namedModelRegistration(object, name) |
1 | A constructor for an object intended to be placed in the array returned from initializeScript, this represents the registration of a JavaScript prototype or ES6 class as a data model via a known name so that other extensions can find and extend |
| namespace | Property |
2 | Gives direct access to the root namespace of the debugger. One could, for example, access the process list of the first debug target via host.namespace.Debugger.Sessions.First().Processes using this property |
| registerNamedModel | registerNamedModel(object, modelName) |
2 | This registers a JavaScript prototype or ES6 class as a data model under the given name. Such a registration allows the prototype or class to be located and extended by other scripts or other debugger extensions. Note that a script should prefer to return a namedModelRegistration object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an initializeScript method in order to clean up. |
| registerExtensionForTypeSignature | registerExtensionForTypeSignature(object, typeSignature) |
2 | This registers a JavaScript prototype or ES6 class as an extension data model for a native type as given by the supplied type signature. Note that a script should prefer to return a typeSignatureExtension object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an initializeScript method in order to clean up. |
| registerPrototypeForTypeSignature | registerPrototypeForTypeSignature(object, typeSignature) |
2 | This registers a JavaScript prototype or ES6 class as the canonical data model (e.g.: visualizer) for a native type as given by the supplied type signature. Note that a script should prefer to return a typeSignatureRegistration object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an uninitializeScriptmethod in order to clean up. |
| parseInt64 | parseInt64(string, [radix]) |
1 | This method acts similarly to the standard JavaScript parseInt method except that it returns a library Int64 type instead. If a radix is supplied, the parse will occur in either base 2, 8, 10, or 16 as indicated. |
| typeSignatureExtension | new typeSignatureExtension(object, typeSignature, [moduleName], [minVersion], [maxVersion]) |
1 | A constructor for an object intended to be placed in the array returned from initializeScript, this represents an extension of a native type described via a type signature by a JavaScript prototype or ES6 class. Such a registration "adds fields" to the debugger's visualization of any type which matches the signature rather than taking it over entirely. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings. |
| typeSignatureRegistration | new typeSignatureRegistration(object, typeSignature, [moduleName], [minVersion], [maxVersion]) |
1 | A constructor for an object intended to be placed in the array returned from initializeScript, this represents a canonical registration of a JavaScript prototype or ES6 class against a native type signature. Such a registration "takes over" the debugger's visualization of any type which matches the signature rather than merely than extending it. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings. |
| unregisterNamedModel | unregisterNamedModel(modelName) |
2 | This unregisters a data model from lookup by the given name undoing any operation performed by registerNamedModel |
| unregisterExtensionForTypeSignature | unregisterExtensionForTypeSignature(object, typeSignature, [moduleName], [minVersion], [maxVersion]) |
2 | This unregisters a JavaScript prototype or ES6 class from being an extension data model for a native type as given by the supplied type signature. It is the logical undo of registerExtensionForTypeSignature. Note that a script should prefer to return a typeSignatureExtension object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an initializeScript method in order to clean up. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings. |
| unregisterPrototypeForTypeSignature | unregisterPrototypeForTypeSignature(object, typeSignature, [moduleName], [minVersion], [maxVersion]) |
2 | This unregisters a JavaScript prototype or ES6 class from being the canonical data model (e.g.: visualizer) for a native type as given by the supplied type signature. It is the logical undo of registerPrototypeForTypeSignature. Note that a script should prefer to return a typeSignatureRegistration object from its initializeScript method rather than doing this imperatively. Any script which makes changes imperatively is required to have an uninitializeScript method in order to clean up. An optional module name and version can restrict the registration. Versions are specified as "1.2.3.4" style strings. |
Diagnostics Functionality
The diagnostics sub-namespace of the host object contains the following.
| Name | Signature | Phase Present | Description |
|---|---|---|---|
| debugLog | debugLog(object...) | 1 | This provides printf style debugging to a script extension. At present, output from debugLog is routed to the output console of the debugger. At a later point in time, there are plans to provide flexibility on routing this output. NOTE: This should not be used as a means of printing user output to console. It may not be routed there in the future. |
Memory Functionality
The memory sub-namespace of the host object contains the following.
| Name | Signature | Phase Present | Description |
|---|---|---|---|
| readMemoryValues | readMemoryValues(location, numElements, [elementSize], [isSigned], [contextInheritor]) |
2 | This reads a raw array of values from the address space of the debug target and places a typed array on top of the view of this memory. The supplied location can be an address (a 64-bit value), a location object, or a native pointer. The size of the array is indicated by the numElements argument. The size (and type) of each element of the array is given by the optional elementSize and isSigned arguments. If no such arguments are supplied, the default is byte (unsigned / 1 byte). If the optional contextInheritor argument is supplied, memory will be read in the context (e.g.: address space and debug target) indicated by the argument; otherwise, it will be read from the debugger's current context. Note that using this method on 8, 16, and 32-bit values results in a fast typed view being placed over the read memory. Using this method on 64-bit values results in an array of 64-bit library types being constructed which is significantly more expensive! |
| readString | readString(location, [contextInheritor]) readString(location, [length], [contextInheritor]) |
2 | This reads a narrow (current code page) string from the address space of a debug target, converts it to UTF-16, and returns the result as a JavaScript string. It may throw an exception if the memory could not be read. The supplied location can be an address (a 64-bit value), a location object, or a native char. If the optional contextInheritor argument is supplied, memory will be read in the context (e.g.: address space and debug target) indicated by the argument; otherwise, it will be read from the debugger's current context. If the optional length argument is supplied, the read string will be of the specified length. |
| readWideString | readWideString(location, [contextInheritor]) readWideString(location, [length], [contextInheritor]) |
2 | This reads a wide(UTF-16) string from the address space of a debug target and returns the result as a JavaScript string. It may throw an exception if the memory could not be read. The supplied location can be an address (a 64-bit value), a location object, or a native wchar_t. If the optional contextInheritor argument is supplied, memory will be read in the context (e.g.: address space and debug target) indicated by the argument; otherwise, it will be read from the debugger's current context. If the optional length argument is supplied, the read string will be of the specified length. |
Data Model Concepts in JavaScript
Data Model Mapping
The following data model concepts map to JavaScript.
| Concept | Native Interface | JavaScript Equivalent |
|---|---|---|
| String Conversion | IStringDisplayableConcept | standard: toString(...){...} |
| Iterability | IIterableConcept | standard: [Symbol.iterator](){...} |
| Indexability | IIndexableConcept | protocol: getDimensionality(...) / getValueAt(...) / setValueAt(...) |
| Runtime Type Conversion | IPreferredRuntimeTypeConcept | protocol: getPreferredRuntimeTypedObject(...) |
String Conversion
The string conversion concept (IStringDisplayableConcept) directly translates to the standard JavaScript toString method. As all JavaScript objects have a string conversion (provided by Object.prototype if not provided elsewhere), every JavaScript object returned to the data model can be converted to a display string. Overriding the string conversion simply requires implementing your own toString.
class myObject
{
//
// This method will be called whenever any native code calls IStringDisplayableConcept::ToDisplayString(...)
//
toString()
{
return "This is my own string conversion!";
}
}
Iterability
The data model's concept of whether an object is iterable or not maps directly to the ES6 protocol of whether an object is iterable. Any object which has a [Symbol.iterator] method is considered iterable. Implementation of such will make the object iterable.
An object which is only iterable can have an implementation such as follows.
class myObject
{
//
// This method will be called whenever any native code calls IIterableConcept::GetIterator
//
*[Symbol.iterator]()
{
yield "First Value";
yield "Second Value";
yield "Third Value";
}
}
Special consideration must be given for objects which are both iterable and indexable as the objects returned from the iterator must include the index as well as the value via a special return type.
Iterable and Indexable
An object which is iterable and indexable requires a special return value from the iterator. Instead of yielding the values, the iterator yields instances of indexedValue. The indicies are passed as an array in the second argument to the indexedValue constructor. They can be multi-dimensional but must match the dimensionality returned in the indexer protocol.
This code shows an example implementaion.
class myObject
{
//
// This method will be called whenever any native code calls IIterableConcept::GetIterator
//
*[Symbol.iterator]()
{
//
// Consider this a map which mapped 42->"First Value", 99->"Second Value", and 107->"Third Value"
//
yield new host.indexedValue("First Value", [42]);
yield new host.indexedValue("Second Value", [99]);
yield new host.indexedValue("Third Value", [107]);
}
}
Indexability
Unlike JavaScript, the data model makes a very explicit differentiation between property access and indexing. Any JavaScript object which wishes to present itself as indexable in the data model must implement a protocol consisting of a getDimensionality method which returns the dimensionality of the indexer and an optional pair of getValueAt and setValueAt methods which perform reads and writes of the object at supplied indicies. It is acceptable to omit either the getValueAt or setValueAt methods if the object is read-only or write-only
class myObject
{
//
// This method will be called whenever any native code calls IIndexableConcept::GetDimensionality or IIterableConcept::GetDefaultIndexDimensionality
//
getDimensionality()
{
//
// Pretend we are a two dimensional array.
//
return 2;
}
//
// This method will be called whenever any native code calls IIndexableConcept::GetAt
//
getValueAt(row, column)
{
return this.__values[row * this.__columnCount + column];
}
//
// This method will be called whenever any native code calls IIndexableConcept::SetAt
//
setValueAt(value, row, column)
{
this.__values[row * this.__columnCount + column] = value;
}
}
Runtime Type Conversion
This is only relevant for JavaScript prototypes/classes which are registered against type system (native) types. The debugger is often capable of performing analysis (e.g. Run-Time Type Information (RTTI) / v-table analysis) to determine the true runtime type of an object from a static type expressed in code. A data model registered against a native type can override this behavior via an implementation of the IPreferredRuntimeTypeConcept. Likewise, a JavaScript class or prototype registered against a native object can provide its own implementation via implementation of a protocol consisting of the getPreferredRuntimeTypedObject method.
Note that while this method can technically return anything, it is considered bad form for it to return something which isn't really the runtime type or a derived type. Such can result in significant confusion for users of the debugger. Overriding this method can, however, be valuable for things such as C-style header+object styles of implementation, etc...
class myNativeModel
{
//
// This method will be called whenever the data model calls IPreferredRuntimeTypeConcept::CastToPreferredRuntimeType
//
getPreferredRuntimeTypedObject()
{
var loc = this.targetLocation;
//
// Perform analysis...
//
var runtimeLoc = loc.Add(runtimeObjectOffset);
return host.createTypedObject(runtimeLoc, runtimeModule, runtimeTypeName);
}
}
See also
Native Debugger Objects in JavaScript Extensions
Native Debugger Objects in JavaScript Extensions - Design and Testing Considerations
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for