在 Azure 应用服务中为 .NET 应用启用快照调试器

项目
09/28/2023

快照调试器当前支持按 Windows 服务计划在 Azure 应用服务上运行的 ASP.NET 和 ASP.NET Core 应用。

建议在使用 Snapshot Debugger 时在基本服务层或更高版本上运行应用程序。

对于大多数应用程序，“免费”和“共享”服务层没有足够的内存或磁盘空间来保存快照。

启用快照调试器

若要为应用启用快照调试器，请遵循下面的说明。

如果你在运行另一种类型的 Azure 服务，则下面提供了用于在其他受支持平台上启用 Snapshot Debugger 的说明：

注意

如果使用的是 .NET Core 预览版，或者应用程序通过依赖程序集直接或间接引用了 Application Insights SDK，请按照为其他环境启用 Snapshot Debugger进行操作，将 Microsoft.ApplicationInsights.SnapshotCollector NuGet 包包含在应用程序中，然后完成下面的其余说明。

Application Insights Snapshot Debugger 的无代码安装遵循 .NET Core 支持策略。有关支持的运行时的详细信息，请参阅 .Net Core 支持策略。

预安装 Snapshot Debugger 作为应用程序服务运行时的一部分，但需启用它才能获得适用于应用服务应用的快照。

部署应用后，请按照以下步骤启用 Snapshot Debugger：

导航到应用服务的 Azure 控制面板。
转到“设置”>“Application Insights”页面。
按页面中的说明创建新资源，或者选择现有 App Insights 资源，以便监视应用。另外，请确保快照调试器的两个开关都为“开” 。
现已使用应用服务应用设置启用了快照调试器。

为中国云启用 Snapshot Debugger

连接字符串属性	中国云
SnapshotEndpoint	`https://snapshot.monitor.azure.cn`

若要详细了解其他连接替代，请参阅 Application Insights 文档。

对引入快照启用 Azure Active Directory 身份验证

Application Insights Snapshot Debugger 支持快照引入进行 AD 身份验证。这意味着，要引入应用程序的所有快照，你的应用程序必须经过身份验证并向 Snapshot Debugger 代理提供所需的应用程序设置。

到目前为止，只有当你应用程序中使用 Application Insights Profiler 来引用和配置 Azure AD 时，Snapshot Debugger 才支持 Azure AD 身份验证。

你可以在下面找到为配置文件引入启用 Azure AD 所需的所有步骤：

创建你要用于对 Application Insights 资源进行身份验证的托管标识并将其添加到你的应用服务。

a. 对于系统分配的托管标识，请参阅以下文档

b. 对于用户分配的托管标识，请参阅以下文档
在 Application Insights 资源中配置和启用 Azure AD。
添加以下应用程序设置，用于让 Snapshot Debugger 代理知道要使用哪个托管标识：

对于系统分配的标识：

应用设置	值
APPLICATIONINSIGHTS_AUTHENTICATION_STRING	Authorization=AAD

对于用户分配的标识：

应用设置	值
APPLICATIONINSIGHTS_AUTHENTICATION_STRING	Authorization=AAD；ClientId={用户分配标识的客户端 ID}

禁用快照调试器

执行与启用快照调试器相同的步骤，但将快照调试器的两个开关都切换到“关” 。

建议对所有应用启用 Snapshot Debugger，以简化应用程序异常的诊断。

Azure Resource Manager 模板

对于 Azure 应用服务，可在 Azure 资源管理器模板中设置应用设置，以启用 Snapshot Debugger 和 Profiler，请参阅下面的模板代码片段：

{
  "apiVersion": "2015-08-01",
  "name": "[parameters('webSiteName')]",
  "type": "Microsoft.Web/sites",
  "location": "[resourceGroup().location]",
  "dependsOn": [
    "[variables('hostingPlanName')]"
  ],
  "tags": { 
    "[concat('hidden-related:', resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName')))]": "empty",
    "displayName": "Website"
  },
  "properties": {
    "name": "[parameters('webSiteName')]",
    "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
  },
  "resources": [
    {
      "apiVersion": "2015-08-01",
      "name": "appsettings",
      "type": "config",
      "dependsOn": [
        "[parameters('webSiteName')]",
        "[concat('AppInsights', parameters('webSiteName'))]"
      ],
      "properties": {
        "APPINSIGHTS_INSTRUMENTATIONKEY": "[reference(resourceId('Microsoft.Insights/components', concat('AppInsights', parameters('webSiteName'))), '2014-04-01').InstrumentationKey]",
        "APPINSIGHTS_PROFILERFEATURE_VERSION": "1.0.0",
        "APPINSIGHTS_SNAPSHOTFEATURE_VERSION": "1.0.0",
        "DiagnosticServices_EXTENSION_VERSION": "~3",
        "ApplicationInsightsAgent_EXTENSION_VERSION": "~2"
      }
    }
  ]
},

不支持的场景

可以在下面找到不支持 Snapshot Collector 的场景：

方案	副作用	建议
在应用程序 (.csproj) 中直接使用 Snapshot Collector SDK 并且已启用高级选项“互操作”时。	本地 Application Insights SDK（包括 Snapshot Collector 遥测）将丢失，因此将没有快照可用。应用程序在启动 `System.ArgumentException: telemetryProcessorTypedoes not implement ITelemetryProcessor.` 时可能会崩溃有关 Application Insights 功能“互操作”的详细信息，请参阅文档。	如果使用高级选项“互操作”，请使用无代码 Snapshot Collector 注入（通过 Azure 门户 UX 启用）

后续步骤

为应用程序生成可触发异常的流量。然后等待 10 到 15 分钟，这样快照就会发送到 Application Insights 实例。
请参见 Azure 门户中的快照。
排查 Snapshot Debugger 问题时如需帮助，请参阅 Snapshot Debugger 故障排除。