使用 IntelliTrace 独立收集器（C#、Visual Basic）

借助 IntelliTrace 独立收集器，可以在生产服务器上或其他环境中收集应用的 IntelliTrace 诊断数据，而无需在目标计算机上安装 Visual Studio，且不更改目标系统的环境。 IntelliTrace 独立收集器适用于 Web、SharePoint、WPF 和 Windows 窗体应用。 完成收集数据后，只需删除收集器即可将其卸载。

要求

• .NET Framework 3.5 或更高版本

• Visual Studio Enterprise（但不是专业版或社区版）用于在开发计算机或其他计算机上打开 .iTrace 文件

  注释

  请确保保存符号 （.pdb） 文件。 若要使用 IntelliTrace 进行调试并单步执行代码，必须具有匹配的源文件和符号文件。 请参阅 部署后诊断问题。

  常见问题

• 哪些应用适用于收集器？

• 如何开始？

• 如何获取最多数据而不减慢应用速度？

• 在何处可以获取 IntelliTrace 数据？

哪些应用适用于收集器？

• ASP.NET 托管在 Internet Information Services（IIS）版本 7.0、7.5、8.0、12.0 和 16.0 上的 Web 应用

• SharePoint 2010 和 SharePoint 2013 应用程序

• Windows Presentation Foundation （WPF） 和 Windows 窗体应用。

如何开始使用？

1. 安装收集器

2. 设置收集器目录的权限

3. 安装 IntelliTrace PowerShell cmdlet 以收集 Web 应用或 SharePoint 应用程序的数据

4. 设置 .iTrace 文件目录的权限

5. 从 Web 应用或 SharePoint 应用程序收集数据

   -或-

   从托管应用收集数据

6. 在 Visual Studio Enterprise 中打开 .iTrace 文件

安装收集器

1. 在应用的服务器上，创建收集器目录，例如： C：\IntelliTraceCollector

2. 从 Visual Studio 安装文件夹获取收集器。

   1. 从安装收集器的文件夹复制 IntelliTraceCollection.cab，例如：

      ..\Microsoft Visual Studio\18\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace

      ..\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace

      或者，对于 Visual Studio 的旧版本：

      ..\Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\12.0.0

   2. 将 IntelliTraceCollection.cab 放在收集器目录中，例如： C：\IntelliTraceCollector

3. 解压缩 IntelliTraceCollection.cab：

   1. 在应用的服务器上，以管理员身份打开命令提示符窗口。

   2. 浏览到收集器目录，例如： C：\IntelliTraceCollector

   3. 使用 扩展 命令以扩展 IntelliTraceCollection.cab 时，必须在结尾包含句点.。

      expand /f:* IntelliTraceCollection.cab .

      注释

      句点 （.） 保留包含本地化集合计划的子文件夹。

设置收集器目录的权限

1. 在应用的服务器上，以管理员身份打开命令提示符窗口。

2. 使用 Windows icacls 命令向服务器管理员授予收集器目录的完全权限。 例如：

   icacls "C:\IntelliTraceCollector" /grant " <Domain\AdministratorID>":F

3. 若要为 Web 应用或 SharePoint 应用程序收集数据，请执行以下作：

   1. 为将运行 IntelliTrace PowerShell cmdlet 的用户授予收集器目录的完整权限。

      例如：

      icacls "C:\IntelliTraceCollector" /grant " <Domain\UserID>":F

   2. 为 Web 应用或 SharePoint 应用程序的应用程序池授予对收集器目录读取和执行权限。

      例如：

      • 对于 DefaultAppPool 应用程序池中的 Web 应用：

        icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RX

      • 在 SharePoint - 80 应用程序池中的 SharePoint 应用程序：

        icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX

安装 IntelliTrace PowerShell cmdlet 以收集 Web 应用或 SharePoint 应用程序的数据

1. 在应用的服务器上，确保已启用 PowerShell。 在大多数版本的 Windows Server 上，可以在 服务器管理器 管理工具中添加此功能。

   

2. 安装 IntelliTrace PowerShell cmdlet。

   1. 以管理员身份打开 PowerShell 命令窗口。

      1. 选择 “开始”、“ 所有程序”、“ 附件”、“ Windows PowerShell”。

      2. 选择以下步骤之一：

         • 在 64 位作系统上，打开 Windows PowerShell 的快捷菜单。 选择 “以管理员身份运行”。

         • 在 32 位作系统上，打开 Windows PowerShell（x86）的快捷菜单。 选择 “以管理员身份运行”。

   2. 在 PowerShell 命令窗口中，使用 Import-Module 命令导入 Microsoft.VisualStudio.IntelliTrace.PowerShell.dll。

      例如：

      Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"

设置 .iTrace 文件目录的权限

1. 在应用的服务器上，创建 .iTrace 文件目录，例如： C：\IntelliTraceLogFiles

   注释

   • 若要避免降低应用速度，请选择本地高速磁盘上不太活跃的位置。
     • 可以将 .iTrace 文件和收集器文件放在同一位置。 但是，如果你有 Web 应用或 SharePoint 应用程序，请确保此位置位于托管应用程序的目录之外。

   重要

   • 仅将 .iTrace 文件目录限制为必须与收集器一起使用的标识。 .iTrace 文件可能包含敏感信息，例如来自用户、数据库、其他源位置和连接字符串的数据，因为 IntelliTrace 可以记录传入方法参数或返回值的任何数据。
     • 确保可以打开 .iTrace 文件的用户有权查看敏感数据。 共享 .iTrace 文件时请小心。 如果其他人必须具有访问权限，请将文件复制到安全的共享位置。

2. 对于 Web 应用或 SharePoint 应用程序，为其应用程序池授予对 .iTrace 文件目录的完整权限。 可以使用 Windows icacls 命令或使用 Windows 资源管理器（或文件资源管理器）。

   例如：

   • 使用 Windows icacls 命令设置权限：

     • 对于 DefaultAppPool 应用程序池中的 Web 应用：

       icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":F

     • 在 SharePoint - 80 应用程序池中的 SharePoint 应用程序：

       icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F

       -或-

   • 若要使用 Windows 资源管理器（或文件资源管理器）设置权限，请执行以下操作：

     1. 打开 .iTrace 文件目录 的属性 。

     2. 在“ 安全 ”选项卡上，选择“ 编辑”， “添加”。

     3. 确保 内置安全主体 显示在 “选择此对象类型 ”框中。 如果不存在，请选择 “对象类型 ”以添加它。

     4. 请确保本地计算机显示在“ 从此位置 ”框中。 如果不存在，请选择 “位置 ”以更改它。

     5. 在 “输入要选择的对象名称 ”框中，为 Web 应用或 SharePoint 应用程序添加应用程序池。

     6. 选择「检查名称」以解决名称。 选择确定。

     7. 确保应用程序池具有完全控制。

从 Web 应用或 SharePoint 应用程序收集数据

1. 若要开始收集数据，请以管理员身份打开 PowerShell 命令窗口，然后运行以下命令：

   Start-IntelliTraceCollection " <ApplicationPool>"<PathToCollectionPlan><FullPathToITraceFileDirectory>

   重要

   运行此命令后，键入 Y 以确认要开始收集数据。

   例如，若要从 SharePoint - 80 应用程序池中的 SharePoint 应用程序收集数据：

   Start-IntelliTraceCollection "SharePoint - 80" "C:\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" "C:\IntelliTraceLogFiles"

   Name	Description
   ApplicationPool	应用程序运行的应用程序池的名称
   PathToCollectionPlan	收集计划的路径，一个 .xml 文件，用于配置收集器的设置。 可以指定收集器附带的计划。 以下计划适用于 Web 应用和 SharePoint 应用程序： - collection_plan.ASP.NET.default.xml 仅收集 IntelliTrace 事件和 SharePoint 事件，包括异常、数据库调用和 Web 服务器请求。 - collection_plan.ASP.NET.trace.xml 收集函数调用和 collection_plan.ASP.NET.default.xml中的所有数据。 此计划适用于详细分析，但它可能会减慢应用的速度超过 collection_plan.ASP.NET.default.xml。 若要避免降低应用速度，请自定义这些计划或创建自己的计划。 为了获得安全性，请将任何自定义计划置于与收集器文件相同的安全位置。 请参阅“创建和自定义 IntelliTrace 集合计划”，以及如何获取最多数据而不减慢应用速度？注意：默认情况下，.iTrace 文件的最大大小为 100 MB。 当 .iTrace 文件达到此限制时，收集器将删除文件最早的条目，以便为较新的条目提供空间。 若要更改此限制，请编辑收集计划 MaximumLogFileSize 的属性。 在哪里可以找到这些收集计划的本地化版本？ 可以在收集器的子文件夹中找到本地化的计划。
   FullPathToITraceFileDirectory	.iTrace 文件目录的完整路径。 安全说明： 提供完整路径，而不是相对路径。

   收集器连接到应用程序池并开始收集数据。

   此时是否可以打开 .iTrace 文件？ 否，在数据收集期间文件被锁定。

2. 重现问题。

3. 若要创建 .iTrace 文件的检查点，请使用以下语法：

   Checkpoint-IntelliTraceCollection " <ApplicationPool>"

4. 若要检查集合状态，请使用以下语法：

   Get-IntelliTraceCollectionStatus

5. 若要停止收集数据，请使用以下语法：

   Stop-IntelliTraceCollection " <ApplicationPool>"

   重要

   运行此命令后，键入 Y 以确认要停止收集数据。 否则，收集器可能会继续收集数据，iTrace 文件将保持锁定状态，或者该文件可能不包含任何有用的数据。

6. 在 Visual Studio Enterprise 中打开 .iTrace 文件

从托管应用收集数据

1. 若要同时启动应用并收集数据，请使用以下语法：

   <FullPathToIntelliTraceCollectorExecutable>\IntelliTraceSC.exe launch /cp:<PathToCollectionPlan>/f:<FullPathToITraceFileDirectoryAndFileName><PathToAppExecutableFileAndFileName>

   例如，从名为 MyApp 的应用收集数据：

   C:IntelliTraceCollectorIntelliTraceSC.exe launch /cp:"C:IntelliTraceCollectorcollection_plan.ASP.NET.default.xml" /f:"C:IntelliTraceLogFilesMyApp.itrace" "C:MyAppMyApp.exe"

   Name	Description
   FullPathToIntelliTraceCollectorExecutable	收集器可执行文件的完整路径，IntelliTraceSC.exe
   PathToCollectionPlan	收集计划的路径，一个 .xml 文件，用于配置收集器的设置。 可以指定收集器附带的计划。 以下计划适用于托管应用： - collection_plan.ASP.NET.default.xml 仅收集 IntelliTrace 事件，包括异常、数据库调用和 Web 服务器请求。 - collection_plan.ASP.NET.trace.xml 收集函数调用和 collection_plan.ASP.NET.default.xml中的所有数据。 此计划适用于详细分析，但它可能会减慢应用的速度超过 collection_plan.ASP.NET.default.xml。 若要避免降低应用速度，请自定义这些计划或创建自己的计划。 为了获得安全性，请将任何自定义计划置于与收集器文件相同的安全位置。 请参阅“创建和自定义 IntelliTrace 集合计划”，以及如何获取最多数据而不减慢应用速度？注意：默认情况下，.iTrace 文件的最大大小为 100 MB。 当 .iTrace 文件达到此限制时，收集器将删除文件最早的条目，以便为较新的条目提供空间。 若要更改此限制，请编辑收集计划 MaximumLogFileSize 的属性。 在哪里可以找到这些收集计划的本地化版本？ 可以在收集器的子文件夹中找到本地化的计划。
   完整路径到ITrace文件目录和文件名	.iTrace 文件目录的完整路径和扩展名为 .itrace 的 .iTrace 文件名。 安全说明： 提供完整路径，而不是相对路径。
   PathToAppExecutableFileAndFileName	托管应用的路径和文件名

2. 通过退出应用停止数据收集。

3. 在 Visual Studio Enterprise 中打开 .iTrace 文件

在 Visual Studio Enterprise 中打开 .iTrace 文件

1. 移动 .iTrace 文件或将其复制到具有 Visual Studio Enterprise（但不是专业版或社区版）的计算机。

2. 双击 Visual Studio 外部的 .iTrace 文件，或从 Visual Studio 内部打开该文件。

   Visual Studio 显示 “IntelliTrace 摘要 ”页。 在大多数部分中，可以查看事件或其他项，选择一个项目，然后在事件发生时使用 IntelliTrace 开始调试。 请参阅 使用保存的 IntelliTrace 数据。

   注释

   若要使用 IntelliTrace 进行调试并单步执行代码，必须在开发计算机上具有匹配的源文件和符号文件。 请参阅 部署后诊断问题。

如何获取最多数据而不减慢应用速度？

IntelliTrace 可以收集大量数据，因此对应用性能的影响取决于 IntelliTrace 收集的数据及其分析的代码类型。 请参阅 优化生产服务器上的 IntelliTrace 集合。

以下是在不减慢应用的情况下获取数据最多的一些方法：

• 仅当认为存在问题或可以重现该问题时，才运行收集器。

  开始收集，重现问题，然后停止收集。 在 Visual Studio Enterprise 中打开 .iTrace 文件并检查数据。 请参阅 在 Visual Studio Enterprise 中打开 .iTrace 文件。

• 对于 Web 应用和 SharePoint 应用程序，收集器会记录共享指定应用程序池的每个应用的数据。 这可能会降低共享同一应用程序池的任何应用的速度，即使你只能在收集计划中为单个应用指定模块。

  若要防止收集器减慢其他应用，请在其自己的应用程序池中托管每个应用。

• 请查看 IntelliTrace 数据收集计划中的事件。 编辑收集计划以禁用与你无关或不感兴趣的事件。

  若要禁用事件，请将 enabled 元素的属性 <DiagnosticEventSpecification> 设置为 false：

  <DiagnosticEventSpecification enabled="false">

  enabled如果该属性不存在，则会启用该事件。

  这如何提高性能？

  • 可以通过禁用与应用无关的事件来缩短启动时间。 例如，为不使用 Windows 工作流的应用禁用 Windows 工作流事件。

  • 可以通过禁用访问注册表但未显示注册表设置问题的应用的注册表事件来提高启动和运行时性能。

• 查看 IntelliTrace 数据收集中计划涉及的模块。 编辑集合计划以仅包含感兴趣的模块：

  1. 打开收集计划。 查找 <ModuleList> 元素。

  2. 在 <ModuleList>中，将 isExclusionList 属性设置为 false.

  3. 使用 <Name> 元素来指定每个模块，可以选择以下之一：文件名、包含字符串值（任何模块名称包含此字符串）或者公钥。

     例如，若要仅从 Fabrikam Fiber Web 应用的主 Web 模块收集数据，请创建如下所示的列表：

  <ModuleList isExclusionList="false">
     <Name>FabrikamFiber.Web.dll</Name>
  </ModuleList>
  

  若要从名称包括“Fabrikam”的任何模块收集数据，请创建如下所示的列表：

  <ModuleList isExclusionList="false">
     <Name>Fabrikam</Name>
  </ModuleList>
  

  若要通过指定其公钥令牌从模块收集数据，请创建如下所示的列表：

  <ModuleList isExclusionList="false">
     <Name>PublicKeyToken:B77A5C561934E089</Name>
     <Name>PublicKeyToken:B03F5F7F11D50A3A</Name>
     <Name>PublicKeyToken:31BF3856AD364E35</Name>
     <Name>PublicKeyToken:89845DCD8080CC91</Name>
     <Name>PublicKeyToken:71E9BCE111E9429C</Name>
  </ModuleList>
  

  这如何提高性能？

  这减少了在应用启动时 IntelliTrace 收集的方法调用信息和其他检测数据的数量。 此数据使你可以：

  • 收集数据后，逐步调试代码。

  • 检查传递给函数调用并从中返回的值。

    为什么不排除模块？

    默认情况下，集合计划通过将isExclusionList属性设置为true来排除模块。 但是，排除特定模块可能仍会收集来自不符合列表条件的模块的数据，而这些模块可能不会引起您的兴趣，例如第三方或开源模块。

• 是否有 IntelliTrace 未收集的数据？

  是的，为了降低性能影响，IntelliTrace 将数据收集限制为传入和返回的基元数据类型的值，以及从方法传入和返回的顶级对象中基元数据类型的值。

  例如，假设你有一个AlterEmployee方法签名，该签名接受一个整数id和一个对象Employeeoldemployee。

  public Employee AlterEmployee(int id, Employee oldemployee)

  该Employee类型具有以下属性： Id和 NameHomeAddress。 Employee与Address类型之间存在关联关系。

  

  收集器记录id、Employee.Id、Employee.Name的值以及从AlterEmployee方法返回的Employee对象。 但是，收集器只记录 Address 对象是否为 null，而不记录其他信息。 收集器也不会记录AlterEmployee方法中有关局部变量的数据，除非其他方法使用这些局部变量作为参数，此时它们将被记录为方法参数。

在何处可以获取 IntelliTrace 数据？

可以从 Visual Studio Enterprise 中的 IntelliTrace 调试会话获取 IntelliTrace 数据。 请参阅 IntelliTrace 功能。

在哪里可以获取详细信息？

使用保存的 IntelliTrace 数据

IntelliTrace

Blogs

远程使用 IntelliTrace 独立收集器

创建和自定义 IntelliTrace 集合计划

优化生产服务器上的 IntelliTrace 集合

Microsoft DevOps

论坛

Visual Studio 调试器