调试器数据模型 C++ 概述Debugger Data Model C++ Overview

本主题概述如何使用调试器数据模型的C++接口,以便扩展和自定义调试器的功能。This topic provides an overview of how to use Debugger Data Model C++ Interfaces to extend and customize the capabilities of the debugger.

本主题是一系列用于描述可从访问接口的一部分C++,如何使用它们来生成C++调试器扩展,以及如何使基于使用的数据模型的其他构造 (例如:JavaScript 或 NatVis) 从C++数据模型扩展。This topic is part of a series which describes the interfaces accessible from C++, how to use them to build a C++ based debugger extension, and how to make use of other data model constructs (e.g.: JavaScript or NatVis) from a C++ data model extension.

调试器数据模型C++概述Debugger Data Model C++ Overview

调试器数据模型C++接口Debugger Data Model C++ Interfaces

调试器数据模型C++对象Debugger Data Model C++ Objects

调试器数据模型C++的其他接口Debugger Data Model C++ Additional Interfaces

调试器数据模型C++概念Debugger Data Model C++ Concepts

调试器数据模型C++脚本Debugger Data Model C++ Scripting


主题部分Topic Sections

本主题包含以下部分:This topic includes the following sections.

调试器数据模型概述C++接口Overview of Debugger Data Model C++ Interfaces

调试器数据模型接口的摘要Summary of Debugger Data Model Interfaces

使用 DbgModelClientEx 库Using the DbgModelClientEx Library


调试器数据模型概述C++接口 Overview of the Debugger Data Model C++ Interface

调试器数据模型是一种可扩展的对象模型,它能够让新调试器扩展(包括 JavaScript、NatVis 和 C++ 中的扩展)使用来自调试器的信息并生成可从调试器及其他扩展访问的信息。The debugger data model is an extensible object model that is central to the way in which new debugger extensions (including those in JavaScript, NatVis, and C++) both consume information from the debugger and produce information that can be accessed from the debugger as well as other extensions. 构造其写入到数据模型的 Api 是从 JavaScript 扩展调试器的较新 (dx) 表达式计算器中也可用或C++扩展。Constructs which are written to the data model APIs are available in the debugger's newer (dx) expression evaluator as well as from JavaScript extensions or C++ extensions.

为了说明调试器数据模型的目标,请考虑此传统的调试器命令。To illustrate the goals of the debugger data model, consider this traditional debugger command.

0: kd> !process 0 0 
PROCESS ffffe0007e6a7780
    SessionId: 1  Cid: 0f68    Peb: 7ff7cfe7a000  ParentCid: 0f34
    DirBase: 1f7fb9000  ObjectTable: ffffc001cec82780  HandleCount:  34.
    Image: echoapp.exe
...

调试程序命令正在使用的二进制掩码,它提供了非标准方式仅输出的文本。The debugger command is using a binary mask and it provides text only output in non-standard ways. 难以使用、 设置格式,或扩展的文本输出,布局是特定于此命令。The text output is difficult to consume, format, or extend and the layout is specific to this command.

调试器数据模型相比这dx (显示调试器对象模型表达式)命令。Contrast this to the debugger data model dx (Display Debugger Object Model Expression) command.

dx @$cursession.Processes.Where(p => p.Threads.Count() > 5)

此命令使用标准的数据模型的可发现、 可扩展和可组合以统一的方式。This command uses a standard data model that is discoverable, extensible and composable in uniform ways.

逻辑上间距内容和扩展对特定对象的名称允许调试器扩展功能的发现。Logically name spacing things and extending on specific objects allows for the discovery of debugger extension functionality.

提示

因为数据模型C++对象接口可以是非常详细,以实现完整C++的数据模型,它使用完整的帮助程序库C++异常,模板编程模式建议。Because the Data Model C++ Object interfaces can be very verbose to implement a full C++ helper library for the data model which uses a full C++ exception and template programming paradigm is recommended. 有关详细信息,请参阅使用 DbgModelClientEx 库本主题中更高版本。For more information, see Using the DbgModelClientEx Library later in this topic.

数据模型是方法的新WinDbg 预览调试器,显示的大多数情况。The data model is the way that the new WinDbg Preview debugger, shows most things. 可以查询、 扩展,或编写脚本,因为它们由数据模型驱动新的用户界面中的许多元素。Many elements in the new UI can be queried, extended, or scripted, because they are powered by the data model. 有关详细信息,请参阅WinDbg 预览版-数据模型For more information, see WinDbg Preview - Data Model.

数据模型浏览窗口显示进程和线程

数据模型体系结构视图Data Model Architectural View

下图总结了调试器的数据模型体系结构的主要元素。The following diagram summarizes the major elements of the debugger data model architecture.

  • 到左侧和右侧,显示 UI 元素,提供对象的访问权限和支持 LINQ 查询与此类功能。To the left side, UI elements are shown that provide access to the objects and support such functionality as LINQ queries.
  • 在关系图的右侧是向调试器数据模型提供数据的组件。On the right side of the diagram are components that provide data to debugger data model. 这包括自定义 NatVis,JavaScript 和C++调试器的数据模型扩展。This includes custom NatVis, JavaScript and C++ debugger data model extensions.

数据模型体系结构视图

对象模型Object Model

调试器数据模型的中心是所有内容都是 IModelObject 接口的实例在其中一个统一的对象表示形式。At the center of the Debugger Data Model is a uniform object representation in which everything is an instance of the IModelObject interface. 虽然此类对象可能表示内部函数 (例如: 一个整数值) 或另一个数据模型接口,它通常表示动态对象 – 元数据键/值元组的字典和一组描述抽象行为的概念。While such an object may represent an intrinsic (e.g.: an integer value) or another data model interface, it often represents a dynamic object – a dictionary of key/value/metadata tuples and a set of concepts which describe abstract behaviors.

下图显示了 IModelObject 如何使用密钥存储包含一个提供程序可以创建、 注册和操作的值。This diagram shows how the IModelObject uses Key Stores to contain values that a provider can create, register and manipulate.

  • 它显示提供程序,提供对对象模型的信息It shows a provider, that provides information to the object model
  • 它显示在左侧IModelObject,即通用对象模型,用于操作对象。On the left it shows the IModelObject, that is the common object model that is used to manipulate objects.
  • 在中心非常密钥存储用于存储和访问值。In the center is the Key Store that is used to store and access values.
  • 它显示在底部概念对象支持的功能,例如将转换为可显示字符串或要编制索引的功能。At the bottom it shows Concepts that support objects with functionality such as the ability to convert to a displayable string or be indexed.

数据模型体系结构视图

数据模型中:使用者视图The Data Model: A Consumer View

下图显示了数据模型的使用者视图。The next diagram shows a consumer view of the data model. 在示例dx (显示调试器对象模型表达式)命令用于查询的信息。In the example the dx (Display Debugger Object Model Expression) command is being used to query information.

  • Dx 命令通过对对象的枚举接口的序列化程序进行通信。The Dx command communicates through a serializer to the object enumeration interface.
  • IDebugHost * 对象用于从调试器引擎中收集信息。IDebugHost* objects are used to gather information from the debugger engine.
  • 使用表达式和语义的评估者将请求发送到调试器引擎。Expression and semantic evaluators are used to send the request to the debugger engine.

数据模型体系结构视图

数据模型中:生成者视图The Data Model: A Producer View

此图显示了数据模型的生成者视图。This diagram shows a producer view of the data model.

  • NatVis 提供程序显示在左侧使用 XML 定义其他功能。A NatVis provider is shown on the left that consumes XML that defines additional functionality.
  • JavaScript 提供程序可以充分利用提供程序的动态概念处理实时的信息。A JavaScript provider can take advantage of Dynamic Provider Concepts to manipulate information in real time.
  • 底部显示的本机代码提供程序还可以定义其他功能。The bottom shows a native code provider that can also define additional functionality.

数据模型体系结构视图

数据模型管理器Data Model Manager

下图显示了中心角色对象的管理中起着数据模型管理器。This diagram shows the central role that the data model manager plays in the management of objects.

  • 数据模型管理器充当中心的注册机构的所有对象。The Data Model Manager acts as a central registrar for all objects.
  • 在左侧它显示如何标准调试器元素,如注册会话和进程。On the left it shows how standard debugger elements such as sessions and process are registered.
  • 命名空间块显示了中央注册列表。The namespace block shows the central registration list.
  • 关系图的右侧会显示两个提供程序,一个用于在最前面,NatVis,C /C++在底部的扩展。The right side of the diagram shows two providers, one for NatVis on the top, and a C/C++ extension on the bottom.

数据模型体系结构视图

调试器数据模型接口的摘要 Summary of Debugger Data Model Interfaces

有多种C++接口组成的数据模型的不同部分。There are a multitude of C++ interfaces which comprise different pieces of the data model. 若要以一致、 简便的方式处理这些接口,它们会细分按常规类别。In order to approach these interfaces in a consistent and easy manner, they are broken down by general category. 此处主要方面:The main areas here:

常规对象模型The General Object Model

第一个也是最重要的一组接口定义如何获取对核心数据模型的访问以及如何访问和操作的对象。The first and most important set of interfaces define how to get access to the core data model and how to access and manipulate objects. IModelObject 是表示数据模型中的每个对象的接口 (像C#的对象)。IModelObject is the interface which represents every object in the data model (much like C#'s object). 这是感兴趣的使用者和生成者到数据模型的主要接口。This is the main interface of interest for both consumers of and producers to the data model. 其他接口是用于访问对象的不同方面的机制。The other interfaces are mechanisms for accessing different aspects of objects. 为此类别定义以下接口:The following interfaces are defined for this category:

DbgEng 和数据模型之间的桥梁Bridges Between DbgEng and the Data Model

IHostDataModelAccessIHostDataModelAccess

主要接口Main Interfaces

IModelObjectIModelObject

IKeyStoreIKeyStore

IModelIteratorIModelIterator

IModelPropertyAccessorIModelPropertyAccessor

IModelMethodIModelMethod

IKeyEnumeratorIKeyEnumerator

IRawEnumeratorIRawEnumerator

IModelKeyReference / IModelKeyReference2IModelKeyReference / IModelKeyReference2

概念接口Concept Interfaces

IStringDisplayableConceptIStringDisplayableConcept

IIterableConceptIIterableConcept

IIndexableConceptIIndexableConcept

IPreferredRuntimeTypeConceptIPreferredRuntimeTypeConcept

IDataModelConceptIDataModelConcept

IDynamicKeyProviderConceptIDynamicKeyProviderConcept

IDynamicConceptProviderConceptIDynamicConceptProviderConcept

管理数据模型和可扩展性Management of Data Models and Extensibility

数据模型管理器是用于管理的核心组件如何发生的所有可扩展性。The Data Model Manager is the core component which manages how all extensibility occurs. 它是一组表映射到扩展点,以及对扩展点的综合构造这两种本机类型的中央存储库。It is the central repository of a set of tables which map both native types to extension points as well as synthetic constructs to extension points. 此外,它是负责对象 (的序号值或字符串到 IModelObject 的转换) 的装箱的实体。In addition, it is the entity which is responsible for the boxing of objects (conversion of ordinal values or strings into IModelObject's).

为此类别定义以下接口:The following interfaces are defined for this category:

常规数据模型管理器访问General Data Model Manager Access

IDataModelManager / IDataModelManager2IDataModelManager / IDataModelManager2

脚本管理Script Management

IDataModelScriptManagerIDataModelScriptManager

IDataModelScriptProviderEnumeratorIDataModelScriptProviderEnumerator

对调试器的类型系统和内存空间的访问Access to the Debugger's Type System and Memory Spaces

调试器的基础类型系统和内存空间中的扩展插件能够做出详细信息公开的使用。The underlying type system and memory spaces of the debugger are exposed in detail for extensions to make use of. 为此类别定义以下接口:The following interfaces are defined for this category:

常规主机 (调试器) 接口General Host (Debugger) Interfaces

IDebugHostIDebugHost

IDebugHostStatusIDebugHostStatus

IDebugHostContextIDebugHostContext

IDebugHostMemory / IDebugHostMemory2IDebugHostMemory / IDebugHostMemory2

IDebugHostErrorSinkIDebugHostErrorSink

IDebugHostEvaluator / IDebugHostEvaluator2IDebugHostEvaluator / IDebugHostEvaluator2

IDebugHostExtensibilityIDebugHostExtensibility

主机 (调试器) 类型系统接口Host (Debugger) Type System Interfaces

IDebugHostSymbolsIDebugHostSymbols

IDebugHostSymbol / IDebugHostSymbol2IDebugHostSymbol / IDebugHostSymbol2

IDebugHostModuleIDebugHostModule

IDebugHostType / IDebugHostType2IDebugHostType / IDebugHostType2

IDebugHostConstantIDebugHostConstant

IDebugHostFieldIDebugHostField

IDebugHostDataIDebugHostData

IDebugHostBaseClass IDebugHostPublicIDebugHostBaseClass IDebugHostPublic

IDebugHostModuleSignatureIDebugHostModuleSignature

IDebugHostTypeSignatureIDebugHostTypeSignature

对脚本的主机 (调试器) 支持Host (Debugger) Support for Scripting

IDebugHostScriptHostIDebugHostScriptHost

创作和使用脚本Authoring and Consuming Scripts

数据模型还具有哪些脚本,以及如何调试一个一般概念。The Data Model also has a general notion of what a script is and how to debug one. 它是完全有可能的调试器扩展出现并定义数据模型和另一种动态语言 (通常是一个脚本编写环境) 之间的常规桥梁。It is entirely possible for a debugger extension to come along and define a general bridge between the data model and another dynamic language (usually a scripting environment). 此组接口是如何完成此操作以及如何调试程序 UI 可使用此类脚本。This set of interfaces is how that is accomplished as well as how a debugger UI can make use of such scripts.

为此类别定义以下接口:The following interfaces are defined for this category:

常规脚本接口General Script Interfaces

IDataModelScriptProviderIDataModelScriptProvider

IDataModelScriptIDataModelScript

IDataModelScriptClientIDataModelScriptClient

IDataModelScriptHostContextIDataModelScriptHostContext

IDataModelScriptTemplateIDataModelScriptTemplate

IDataModelScriptTemplateEnumeratorIDataModelScriptTemplateEnumerator

IDataModelNameBinderIDataModelNameBinder

脚本调试器接口Script Debugger Interfaces

IDataModelScriptDebugIDataModelScriptDebug

IDataModelScriptDebugClientIDataModelScriptDebugClient

IDataModelScriptDebugStackIDataModelScriptDebugStack

IDataModelScriptDebugStackFrameIDataModelScriptDebugStackFrame

IDataModelScriptDebugVariableSetEnumeratorIDataModelScriptDebugVariableSetEnumerator

IDataModelScriptDebugBreakpointIDataModelScriptDebugBreakpoint

IDataModelScriptDebugBreakpointEnumeratorIDataModelScriptDebugBreakpointEnumerator

使用 DbgModelClientEx 库 Using the DbgModelClientEx Library

概述Overview

数据模型C++对象的接口连接到数据模型可以变得非常冗长,来实现。The Data Model C++ Object Interfaces to the data model can be very verbose to implement. 虽然它们允许数据模型的完整操作,它们需要实现的多个较小接口来扩展数据模型 (例如: 为每个动态 fetchable 属性添加 IModelPropertyAccessor 实现)。While they allow for full manipulation of the data model, they require implementation of a number of small interfaces to extend the data model (e.g.: an IModelPropertyAccessor implementation for each dynamic fetchable property which is added). 除此之外,HRESULT 基于编程模型将添加大量的模板代码,用于错误检查。In addition to this, the HRESULT based programming model adds a significant amount of boiler plate code that is used for error checking.

为了尽量减少此工作的一部分,是一个完整的C++的数据模型,它使用完整的帮助程序库C++的异常和模板编程模式。In order to minimize some of this work, there is a full C++ helper library for the data model which uses a full C++ exception and template programming paradigm. 当使用或扩展数据模型时,可更简洁的代码,建议使用此库的使用。Use of this library allows for more concise code when consuming or extending the data model and is recommended.

帮助程序库中有两个重要的命名空间:There are two important namespaces in the helper library:

Debugger::DataModel::ClientEx-消耗的数据模型的帮助程序Debugger::DataModel::ClientEx - helpers for consumption of the data model

Debugger::DataModel::ProviderEx-数据模型的扩展的帮助程序Debugger::DataModel::ProviderEx - helpers for extension of the data model

有关使用 DbgModelClientEx 库的其他信息,请参阅此 github 站点上的自述文件:For additional information on using the DbgModelClientEx library, see the readme file at this github site:

https://github.com/Microsoft/WinDbg-Libraries/tree/master/DbgModelCppLib

HelloWorldC++示例HelloWorld C++ Sample

若要了解可以如何使用 DbgModelClientEx 库,查看数据模型 HelloWorldC++此处的示例。To see how the DbgModelClientEx library can be used, review the Data Model HelloWorld C++ sample here.

https://github.com/Microsoft/WinDbg-Samples/tree/master/DataModelHelloWorld

示例包括:The sample includes:

  • HelloProvider.cpp-这是进程的添加新的示例属性"Hello"到调试器的这一概念的提供程序类的实现。HelloProvider.cpp - This is an implementation of a provider class which adds a new example property "Hello" to the debugger's notion of a process.

  • SimpleIntroExtension.cpp-这是进程的一个简单的调试器扩展,也就是进程的添加一个新的示例属性"Hello"到调试器的这一概念。SimpleIntroExtension.cpp - This is a simple debugger extension which adds a new example property "Hello" to the debugger's notion of a process. 此扩展是针对的数据模型 C + + 17 帮助程序库编写的。This extension is written against the Data Model C++17 Helper Library. 目前,最好编写针对此库而不是原始 COM ABI 由于粘附代码所需的卷 (和复杂性) 扩展。It is far preferable to write extensions against this library rather than the raw COM ABI due to the volume (and complexity) of glue code which is required.

JavaScript 和 COM 示例JavaScript and COM Samples

为了更好地了解写入调试器扩展与数据模型的不同方法,有三个版本的数据模型 HelloWorld 扩展可用此处:In order to better understand the varying ways to write a debugger extension with the data model, there are three versions of the data model HelloWorld extension available here:

https://github.com/Microsoft/WinDbg-Samples/tree/master/DataModelHelloWorld

  • JavaScript-以 JavaScript 编写的版本JavaScript - A version written in JavaScript

  • C + + 17-编写针对数据模型中 C + + 17 的客户端库的版本C++17 - A version written against the Data Model C++17 Client Library

  • COM-编写对原始 COM ABI (仅使用 WRL 适用于 COM 帮助程序) 的版本COM - A version written against the raw COM ABI (only using WRL for COM helpers)


相关主题Related topics

调试器数据模型C++概述Debugger Data Model C++ Overview

调试器数据模型C++接口Debugger Data Model C++ Interfaces

调试器数据模型C++对象Debugger Data Model C++ Objects

调试器数据模型C++的其他接口Debugger Data Model C++ Additional Interfaces

调试器数据模型C++概念Debugger Data Model C++ Concepts

调试器数据模型C++脚本Debugger Data Model C++ Scripting