IDebugHostSymbols：：CreateTypeSignature 方法（dbgmodel.h）

2025-02-06

CreateTypeSignature 方法创建一个签名，该签名可用于通过包含模块和类型名称来匹配一组具体类型。类型名称签名字符串的格式特定于正在调试的语言（和调试主机）。对于 C/C++，签名字符串等效于 NatVis 类型规范。也就是说，签名字符串是模板参数允许通配符（指定为 *）的类型名称。

语法

HRESULT CreateTypeSignature(
  PCWSTR                  signatureSpecification,
  IDebugHostModule        *module,
  IDebugHostTypeSignature **typeSignature
);

参数

signatureSpecification

用于标识此签名适用的类型的签名字符串。此字符串的格式特定于正在调试的语言。对于 C/C++，这相当于 NatVis 类型规范。这是模板参数允许通配符（指定为 *）的类型名称。

module

如果指定，则仅给定模块中包含的类型与签名匹配。如果未指定，则任何模块中的类型都可能匹配签名。

typeSignature

此处返回创建的类型签名对象。

返回值

此方法返回指示成功或失败的 HRESULT。

言论

示例代码

ComPtr<IDebugHost> spHost; /* get the host */

ComPtr<IDebugHostSymbols> spSym;
if (SUCCEEDED(spHost.As(&spSym)))
{
    // Create a type signature for MyTemplateType<*>
    ComPtr<IDebugHostTypeSignature> spSig1;
    if (SUCCEEDED(spSym->CreateTypeSignature(L"MyTemplateType<*>", 
                                             nullptr, 
                                             &spSig1)))
    {
        // spSig1 is a type signature which will match any concrete template 
        // type with a base name of MyTemplateType and *ANY* template arguments.
        // This is true regardless of the module in which the type is contained.
    }

    ComPtr<IDebugHostModule> spMyModule;
    if (SUCCEEDED(spSym->FindModuleByName(USE_CURRENT_HOST_CONTEXT, 
                                          L"MyModule.dll", 
                                          &spMyModule)))
    {
        // Create a type signature for MyTemplateType<*> within MyModule.dll.
        ComPtr<IDebugHostTypeSignature> spSig2;
        if (SUCCEEDED(spSym->CreateTypeSignature(L"MyTemplateType<*>", 
                                                 nullptr, 
                                                 &spSig2)))
        {
            // spSig2 is a type signature which will match any concrete 
            // template type with a base name of MyTemplateType and *ANY* 
            // template arguments that is within the particular MyModule.dll 
            // that's in the current UI context (e.g.: process) of the debugger.
            // This means if the host is debugging multiple processes
            // and you switch processes, a MyTemplateType<*> in an identically
            // named and versioned MyModule.dll will *NOT* match this signature.
        }
    }
}

FindModuleByName、CreateTypeSignature 和 CreateTypeSignatureForModuleRange 中的符号模块匹配的差异

FindModuleByName 将允许传递的模块名称是模块的实际映像名称（例如“我的 Module.dll”，或者可以在调试器引擎（例如：MyModule 或 MyModule_<hex_base>）中引用它的名称。

调用 CreateTypeSignatureForModuleRange 并传递名称/nullptr/nullptr 将创建与任何版本名称匹配的任何模块的签名。

传递给 CreateTypeSignature 函数的模块名称将仅接受模块的真实图像名称（例如：MyModule.dll）。

调用 FindModuleByName，然后使用该模块创建一个签名，该签名将仅匹配传递给它的模块的特定实例。如果加载的模块有两个副本（例如：在 64 位 Windows 上运行的 32 位进程中的 ntdll），它只会匹配传递的特定实例。如果卸载并重新加载了 DLL，该 DLL 也不会再匹配。签名与调试器已知的模块的特定实例相关联。