dotTrace 2025.2 Help

使用 API 控制分析会话

profiling API 提供了许多类，允许您控制分析过程。 例如，直接从您的应用程序代码中，您可以：

  • 开始收集分析数据： MeasureProfiler.StartCollectingData()，

  • 停止收集数据： MeasureProfiler.StopCollectingData()，

  • 将数据保存到磁盘： MeasureProfiler.SaveData()，

  • 以及更多。

有关 API 类的详细信息，请参阅 API 参考。

有两个主要场景需要使用 profiling API：

分析代码的特定部分

API 允许您缩小分析范围，仅分析您感兴趣的代码。 例如，有时很难在正确的时刻点击 获取快照 按钮。 使用 profiling API，您可以在代码的确切位置执行“获取快照”调用。

请注意，dotTrace 2018.3 及更早版本使用了另一个版本的 profiling API（有关此 API 的更多信息，请参阅 dotTrace 2018.3 文档）。 此 API 仍受支持，但我们强烈建议您使用本节中描述的最新 API 版本。

主要概念：

  • API 的源代码可在 GitHub 上获取。 代码以 Apache 许可证分发。

  • profiling API 作为 JetBrains.Profiler.API NuGet 包分发，您需要在项目中引用它。

  • 要启用 API，您必须在 profiler options 中启用 如何控制性能分析 | 使用 API 参数并启动分析会话。

  • 使用 API 时，与普通分析会话相比，唯一的区别在于您如何控制会话：您需要调用相应的 API 方法，而不是点击 profiling controller 中的按钮。

  • 如果您在没有分析的情况下运行应用程序，对 API 方法的调用将被忽略。 API 不会抛出任何错误。

  • 控制分析会话的主要类是 MeasureProfiler 静态类。

  • 要开始收集分析数据，请调用 MeasureProfiler.StartCollectingData()。 这相当于按下 启动 按钮。

  • 要停止收集数据并将其保存到磁盘，请调用 MeasureProfiler.SaveData()——相当于按下 获取快照并等待 按钮。

  • 要丢弃数据而不保存，请调用 MeasureProfiler.DropData()——相当于按下 删除 按钮。

  • 要停止收集分析数据而不将其保存到磁盘，请调用 MeasureProfiler.StopCollectingData()。 通常，您不需要使用此方法。 请注意，此方法不适用于 Timeline profiling type ，并且会被分析器忽略。

  • 在 Windows 上，Timeline 分析需要后台运行 ETW 服务。 要启动此服务，需要管理员权限。 因此，每次启动分析会话时，dotTrace 都会提示您提升权限。 为避免这种情况，请使用 <dotTrace_installation_directory>\x64\JetBrains.ETW.Collector.Host.exe 文件手动运行服务。 另一种选择是使用 <dotTrace_installation_directory>\Msi.x64\EtwService.msi 安装文件安装服务。 在这种情况下，服务将在 Windows 启动时运行。

    在 macOS 和 Linux 上，Timeline 分析不需要任何外部服务。

要使用 API 分析代码的特定部分

  1. 在项目中引用 JetBrains.Profiler.API NuGet 包。

  2. 根据您的用例需要，将 MeasureProfiler 类的方法调用插入到代码中。 例如：

    private void SomeMethod() { MeasureProfiler.StartCollectingData(); ... // Here goes some code that I want to profile MeasureProfiler.SaveData(); }

  3. 从 dotTrace、JetBrains Rider 或 Visual Studio 内启动应用程序分析，并在 profiler options 中选择 如何控制性能分析 | 使用 API 参数。 *

创建自分析应用程序

顾名思义，在此场景中，应用程序会自行分析。 与之前的场景相比，主要区别在于如何启动分析。 如果您使用 profiling API 分析代码的特定部分，您需要手动启动会话（例如，使用 dotTrace 界面）。 对于自分析应用程序，会话是直接从应用程序代码中启动的。

主要概念：

  • 自分析 API 是一个单独的 JetBrains.Profiler.SelfApi NuGet 包，您需要在项目中引用它。

  • 为了控制分析会话，API 使用 dotTrace 命令行工具。

  • 命令行工具不是包的一部分。 当您使用 DotTrace.Init() 方法初始化 API 时，API 会下载最新版本的 JetBrains.dotTrace.CommandLineTools NuGet 包（Windows、 Linux、 macOS）。

  • 默认情况下，包中的工具会保存到 %LOCALAPPDATA%\JetBrains\Profiler 文件夹。 要指定其他位置，请使用 downloadTo 参数和 DotTrace.Init() 方法。

  • 如果工具的包已存在，则不会下载新的包。

  • 要配置分析会话，例如指定保存快照的路径，您必须使用 DotTrace.Config 类的实例。

  • 要启动分析会话，您需要通过调用 DotTrace.Attach() 方法将分析器附加到应用程序进程。 如果您有分析配置（DotTrace.Config 的实例），您应该将其作为参数指定： DotTrace.Attach(config)

  • DotTrace.Attach() 不会开始收集分析数据。 要执行此操作，您需要调用 DotTrace.StartCollectingData() 方法。

  • 由于自分析 API 会附加到进程，因此它对可用的分析类型有一定限制。 默认情况下，API 使用 Sampling 分析类型。 或者，您可以使用 Timeline 分析类型。 为此，您需要使用 UseTimelineProfilingType() 方法和 DotTrace.Config 类。

  • 要获取性能快照，请调用 DotTrace.SaveData() 方法。 快照将保存到 DotTrace.Config 中指定的目录。 如果没有分析配置，快照将保存到应用程序的工作目录。

  • 请注意，在调用 DotTrace.SaveData() 后，分析器会停止收集数据。 要重新开始收集数据，您需要再次调用 DotTrace.StartCollectingData()。

  • 要结束分析会话，请调用 DotTrace.Detach() 方法。

  • 您可以同时使用自分析 API 和 profiling API。

向应用程序添加自分析功能

  1. 在项目中引用 JetBrains.Profiler.SelfApi NuGet 包。

  2. 通过调用 DotTrace.Init() 方法初始化自分析 API。 请注意，首次初始化可能需要一些时间，因为 API 需要下载 dotTrace 命令行工具。 如果您希望跟踪下载过程并能够取消下载，请直接使用 DotTrace.InitAsync() 方法。 它允许您使用 CancellationToken 并通过回调变量跟踪进度。

  3. 根据您的用例需要添加 API 调用：

    • 如果您只需要一个快照：

      static void Main(string[] args) { ... // here goes some init code // initialize the API and download the tool (if needed) DotTrace.Init(); // config that sets the save directory var config = new DotTrace.Config(); config.SaveToDir("C:\\Temp\\Snapshot"); // start profiling session DotTrace.Attach(config); // start collecting data DotTrace.StartCollectingData(); SomeMethod(); // end session DotTrace.Detach(); } private void SomeMethod() { ... // here goes some code that I want to profile // get a snapshot and save it DotTrace.SaveData(); }

    • 如果您需要多个快照：

      static void Main(string[] args) { ... // here goes some init code // initialize the API and download the tool (if needed) DotTrace.Init(); // config that sets the save directory var config = new DotTrace.Config(); config.SaveToDir("C:\\Temp\\Snapshot"); // start profiling session DotTrace.Attach(config); // start collecting data DotTrace.StartCollectingData(); SomeMethod(); // end session DotTrace.Detach(); } private void SomeMethod(IEnumerable<String> collection) { foreach (var item in collection) { ... // here goes some code that I want to profile // get a snapshot and save it DotTrace.SaveData(); // start collecting data again DotTrace.StartCollectingData(); } }
最后修改日期： 2025年 9月 28日
控制分析会话API 参考