为 .NET Core 设置 Cloud Debugger

概览

本页面介绍如何配置您的环境和.NET Core 应用以使用 Cloud Debugger。对于一些环境，您必须明确指定访问权限范围，以让 Cloud Debugger 代理发送数据。我们建议尽可能设置最广泛的访问权限范围，然后使用 Identity and Access Management 来限制访问权限。为符合此最佳做法，请使用 cloud-platform 选项将访问权限范围设置为所有 Cloud API。

语言版本和计算环境

Cloud Debugger 适用于以下计算环境中的 .NET Core 1.0 到 2.1：

App Engine 标准环境	App Engine 柔性环境	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos	在其他位置运行的虚拟机和容器	Cloud Functions

设置 Cloud Debugger

要设置 Cloud Debugger，请完成以下任务：

验证是否为您的项目启用了 Cloud Debugger API。
在您正在使用的计算环境中安装并配置 Debugger。
选择您的源代码。

验证 Cloud Debugger API 是否已启用

要开始使用 Cloud Debugger，请确保已启用 Cloud Debugger API。默认情况下，系统会为大多数项目启用 Cloud Debugger。
启用 Cloud Debugger API

App Engine 标准环境

在 App Engine 标准环境中不支持 .NET Core 版 Cloud Debugger 代理。

App Engine 柔性环境

将 app.yaml 中的 runtime 更改为 custom：
```
runtime: custom
env: flex
```

使用自定义 Dockerfile：

FROM gcr.io/dotnet-debugger/aspnetcore:2.0
COPY . /app
WORKDIR /app

# If you don't have source context delete the below line.
# See 'Selecting source code automatically' below for more information.
COPY ./source-context.json /usr/share/dotnet-debugger/agent/
ENTRYPOINT ["/usr/share/dotnet-debugger/start-debugger.sh", "dotnet", "APPLICATION.dll"]

其中：

APPLICATION 是您要运行和调试的二进制文件。

现在，Google Cloud 的运维套件便可与您的应用搭配使用。

要让控制台中的“调试”页面自动显示与已部署应用相匹配的源代码，请参阅自动选择源代码。

Google Kubernetes Engine

GCLOUD

要使用 gcloud 启用 Debugger，请完成以下步骤：

创建集群，并为其指定以下访问权限范围之一：
- https://www.googleapis.com/auth/cloud-platform 授予集群对所有 Google Cloud API 的访问权限。
- https://www.googleapis.com/auth/cloud_debugger 仅授予集群对 Debugger API 的访问权限。使用此访问范围来强化集群的安全性。
```
gcloud container clusters create example-cluster-name \
       --scopes=https://www.googleapis.com/auth/cloud_debugger
```
注意：集群的访问权限范围一经创建便无法更改。
在 Dockerfile 中添加以下几行代码，以将 Debugger 代理添加到您的容器化应用中：
```
FROM gcr.io/dotnet-debugger/aspnetcore:2.0
COPY . /app
WORKDIR /app
# If you don't have the source-context.json file, delete the `COPY` line below.
# See running locally below for more information.
COPY ./source-context.json /usr/share/dotnet-debugger/agent/

ENV STACKDRIVER_DEBUGGER_MODULE=MODULE
ENV STACKDRIVER_DEBUGGER_VERSION=VERSION

# If not running on Google Cloud, uncomment and set the following:
# ENV GOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_FILE
ENTRYPOINT ["/usr/share/dotnet-debugger/start-debugger.sh", "dotnet", "APPLICATION.dll"]
```
其中：
- source-context.json 是包含源上下文配置的 JSON 格式文件。如需了解如何生成此文件，请参阅自动选择源代码。
- MODULE 是应用的名称。它与版本一起在控制台中标识应用。示例：MyApp、Backend 或 Frontend。
- VERSION 是应用的版本（例如构建 ID）。控制台将正在运行的应用显示为 MODULE - VERSION。示例：v1.0、build_147 或 v20160520。
- CREDENTIALS_FILE 是服务帐号凭据 JSON 文件的路径。
- APPLICATION 是正在运行并且连接了 Debugger 的.NET Core 应用的入口点。

您现在可以在部署容器化应用时使用 Debugger 了。

如需详细了解如何创建集群，请参阅创建集群。

控制台

如需使用 Google Cloud Console 启用 Debugger，请完成以下步骤：

在节点池部分中，选择安全，然后选择针对每个 API 设置访问权限。
启用 Debugger。
选项：选择允许所有 Cloud API 的全面访问权限。

现在，Debugger 便可与您的应用搭配使用。

要让控制台中的“调试”页面自动显示与已部署应用相匹配的源代码，请参阅自动选择源代码。

Compute Engine

在 Compute Engine 环境中不支持 .NET Core 版 Cloud Debugger 代理。

本地

在本地运行应用时，如需使用 Google Cloud 的运维套件，请执行以下操作：

将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为指向 JSON 服务帐号完整文件路径。
将 STACKDRIVER_DEBUGGER_MODULE 环境变量设置为要调试的组件的名称。此模块名称将显示在允许调试的模块的控制台列表中。
将 STACKDRIVER_DEBUGGER_VERSION 环境变量设置为要调试的模块的逻辑版本。这样，您就可以在控制台中调试该模块的多个逻辑版本。
将 STACKDRIVER_DEBUGGER_DEBUGGER 环境变量设置为指向 Google Cloud 的运维套件二进制文件所在的位置。
如果在 Linux 上运行，请设置 LD_LIBRARY_PATH 环境变量以包含 Google Cloud 的运维套件目录。

构建 .NET Core 应用时，请使用您的代码添加和部署 PDB 文件。在每个 PDB 文件中添加以下几行：

    <PropertyGroup>
      <TargetFramework>netcoreapp2.1</TargetFramework>
      <DebugType>portable</DebugType>
    </PropertyGroup>

请注意，在调试 Release 构建时，变量可能被错误命名或丢失。