C++ 生成见解 SDK

C++ Build Insights SDK 与 Visual Studio 2017 及更高版本兼容。 若要查看这些版本对应的文档，请将本文的 Visual Studio“版本”选择器控件设置为 Visual Studio 2017 或更高版本。 它位于此页面上目录表的顶部。

C++ Build Insights SDK 是一个 API 集合，可便于在 C++ Build Insights 平台基础之上创建个性化工具。 本页提供了有助于你入门的简要概述。

获取 SDK

可以将 C++ Build Insights SDK 下载为 NuGet 包，具体步骤如下：

1. 在 Visual Studio 2017 及更高版本中，新建 C++ 项目。
2. 在“解决方案资源管理器”窗格中，右键单击你的项目。
3. 选择关联菜单中的“管理 NuGet 包”。
4. 选择右上角的“nuget.org”包源。
5. 搜索最新版 Microsoft.Cpp.BuildInsights 包。
6. 选择“安装”。
7. 接受许可证。

继续阅读有关此 SDK 的一般概念的信息。 你还可以访问官方的 C++ Build Insights 示例 GitHub 存储库，以查看使用此 SDK 的实际 C++ 应用程序示例。

收集跟踪

若要使用 C++ Build Insights SDK 分析来自 MSVC 工具链的事件，需要先收集跟踪。 此 SDK 使用 Windows 事件跟踪 (ETW) 作为基础跟踪技术。 可以通过两种方式来收集跟踪：

方法 1：在 Visual Studio 2019 及更高版本中使用 vcperf

1. 打开适用于 VS 2019 的提升的 x64 本机工具命令提示。

2. 运行以下命令：vcperf /start MySessionName

3. 生成项目。

4. 运行以下命令：vcperf /stopnoanalyze MySessionName outputTraceFile.etl

   重要

   使用 vcperf 停止跟踪时，请运行 /stopnoanalyze 命令。 不能使用 C++ Build Insights SDK 来分析由常规 /stop 命令停止的跟踪。

方法 2：以编程方式

使用下面这些 C++ Build Insights SDK 跟踪收集函数来以编程方式启动和停止跟踪。 执行这些函数调用的程序必须有管理权限。 只有启动和停止跟踪函数需要管理权限。 C++ Build Insights SDK 中的其他所有函数都可以在没有管理权限的情况下执行。

与跟踪收集相关的 SDK 函数

接下来的各部分介绍了如何配置分析或重新记录会话。 这是合并的功能函数（如 StopAndAnalyzeTracingSession）所必需的。

使用跟踪

有了 ETW 跟踪之后，使用 C++ Build Insights SDK 来解包它。 此 SDK 以一种可便于快速开发工具的格式提供事件。 不建议在不使用此 SDK 的情况下使用原始 ETW 跟踪。 MSVC 使用的事件格式是没有文档记录的，经过优化可以扩展为大型生成，并且很难理解。 此外，C++ Build Insights SDK API 是稳定的，而原始 ETW 跟踪格式可能会在不另行通知的情况下发生变更。

与跟踪使用相关的 SDK 类型和函数

分析和重新记录

跟踪使用是通过分析会话或重新记录会话来完成的。

使用常规分析适用于大多数情况。 使用这种方法，可以灵活地选择输出格式：printf 文本、xml、JSON、数据库、REST 调用等。

重新记录用于需要生成 ETW 输出文件的特殊用途分析。 使用重新记录，可以将 C++ Build Insights 事件转换为采用你自己的 ETW 事件格式。 重新记录的一种合适用法是，将 C++ Build Insights 数据挂钩到现有的 ETW 工具和基础结构。 例如，vcperf 使用了重新记录接口。 这是因为它必须生成作为 ETW 工具的 Windows Performance Analyzer 可以理解的数据。 如果你计划使用重新记录接口，则需要预先了解 ETW 的工作原理。

创建 analyzer 组

请务必了解如何创建组。 这是一个示例，展示了如何创建一个打印 Hello, world! 的分析器组。对于它收到的每个活动开始事件。

using namespace Microsoft::Cpp::BuildInsights;

class Hello : public IAnalyzer
{
public:
    AnalysisControl OnStartActivity(
        const EventStack& eventStack) override
    {
        std::cout << "Hello, " << std::endl;
        return AnalysisControl::CONTINUE;
    }
};

class World : public IAnalyzer
{
public:
    AnalysisControl OnStartActivity(
        const EventStack& eventStack) override
    {
        std::cout << "world!" << std::endl;
        return AnalysisControl::CONTINUE;
    }
};

int main()
{
    Hello hello;
    World world;

    // Let's make Hello the first analyzer in the group
    // so that it receives events and prints "Hello, "
    // first.
    auto group = MakeStaticAnalyzerGroup(&hello, &world);

    unsigned numberOfAnalysisPasses = 1;

    // Calling this function initiates the analysis and
    // forwards all events from "inputTrace.etl" to my analyzer
    // group.
    Analyze("inputTrace.etl", numberOfAnalysisPasses, group);

    return 0;
}

使用事件

与事件相关的 SDK 类型和函数

活动和简单事件

事件分为“活动”和“简单事件”这两类。 活动是指正在进行的进程，有开始时间，也有结束时间。 简单事件是准时发生的，没有持续时间。 当使用 C++ Build Insights SDK 分析 MSVC 跟踪时，你会在活动开始和停止时收到单独的事件。 当一个简单事件发生时，你将只收到一个事件。

父子关系

活动和简单事件通过父子关系相互关联。 活动或简单事件的父级是包含它们的活动。 例如，在编译源文件时，编译器必须先分析文件，再生成代码。 分析文件和代码生成这两个活动都是编译器活动的子级。

由于简单事件没有持续时间，因此其内部不会发生其他任何事件。 所以，简单事件从来没有任何子级。

每个活动和简单事件的父子关系在事件表中指明。 使用 C++ Build Insights 事件时，请务必了解这些关系。 你常常不得不依赖他们来理解事件的完整上下文。

属性

所有事件都具有以下属性：

除简单事件之外的所有活动也都具有以下属性：

有些事件除了上面提到的属性外，还有它们自己的属性。 在这种情况下，这些附加属性列在事件表中。

使用 C++ Build Insights SDK 提供的事件

事件堆栈

每当 C++ Build Insights SDK 提供事件时，它都以堆栈的形式出现。 堆栈中的最后一个条目是当前事件，在它之前的条目是它的父层次结构。 例如，LTCG 启动和停止事件发生在链接器的第 1 阶段。 在这种情况下，你收到的堆栈包含： [LINKER, PASS1, LTCG]。 父层次结构很方便，因为可以将事件追溯到它的根。 如果上面提到的 LTCG 活动比较慢，则可以立即了解涉及到哪个链接器调用。

匹配事件和事件堆栈

C++ Build Insights SDK 为你提供了跟踪中的所有事件，但大多数情况下你只关注其中一部分。 在某些情况下，你可能只关注事件堆栈的一部分。 SDK 提供了一些工具，可帮助你快速提取所需的事件或事件堆栈，并拒绝不需要的事件或事件堆栈。 这是通过下面这些匹配函数来完成的：

事件堆栈匹配函数（如 MatchEventStack）在描述要匹配的父层次结构时允许存在间隙。 例如，你可能会表示自己关注 [LINKER, LTCG] 堆栈。 它还会匹配 [LINKER, PASS1, LTCG] 堆栈。 指定的最后一个类型必须是要匹配的事件类型，并且不属于父层次结构。

Capture 类

使用 Match* 函数需要指定要匹配的类型。 这些类型是从捕获类列表中选择的。 捕获类分为几个类别，如下所述。

请参阅事件表，了解可以使用哪些捕获类来匹配每个事件。

匹配后：使用捕获的事件

在成功完成匹配后，Match* 函数便会构造捕获类对象，并将它们转发给指定的函数。 使用这些捕获类对象可以访问事件的属性。

示例

AnalysisControl MyAnalyzer::OnStartActivity(const EventStack& eventStack)
{
    // The event types to match are specified in the PrintIncludes function
    // signature.  
    MatchEventStackInMemberFunction(eventStack, this, &MyAnalyzer::PrintIncludes);
}

// We want to capture event stacks where:
// 1. The current event is a FrontEndFile activity.
// 2. The current FrontEndFile activity has at least one parent FrontEndFile activity
//    and possibly many.
void PrintIncludes(FrontEndFileGroup parentIncludes, FrontEndFile currentFile)
{
    // Once we reach this point, the event stack we are interested in has been matched.
    // The current FrontEndFile activity has been captured into 'currentFile', and
    // its entire inclusion hierarchy has been captured in 'parentIncludes'.

    cout << "The current file being parsed is: " << currentFile.Path() << endl;
    cout << "This file was reached through the following inclusions:" << endl;

    for (auto& f : parentIncludes)
    {
        cout << f.Path() << endl;
    }
}