为 .NET Core 设置 Cloud Debugger

概览

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

语言版本和计算环境

Cloud Debugger 适用于以下计算环境中的 .NET Core 1.0 和更高版本:

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

设置 Cloud Debugger

要设置 Cloud Debugger,请完成以下任务:

  1. 验证是否为您的项目启用了 Cloud Debugger API。

  2. 在您正在使用的计算环境中安装并配置 Debugger。

  3. 选择您的源代码。

验证 Cloud Debugger API 是否已启用

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

App Engine 标准环境

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

App Engine 柔性环境

  1. 将 app.yaml 中的 runtime 更改为 custom

    runtime: custom
    env: flex
    
  2. 使用自定义 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 的运维套件便可与您的应用搭配使用。

要让 Cloud Console 中的“调试”页面可以自动显示与已部署应用匹配的源代码,请参阅自动选择源代码

Google Kubernetes Engine

GCLOUD

要使用 gcloud 启用 Debugger,请完成以下步骤:

  1. 创建集群,并为其指定以下访问权限范围之一:

    • 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
    
  2. 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 是应用的名称。它与版本一起用于在 Cloud Console 中标识应用。示例:MyAppBackendFrontend

    • VERSION 是应用的版本(例如构建 ID)。Cloud Console 将正在运行的应用显示为 MODULE - VERSION。示例:v1.0build_147v20160520

    • CREDENTIALS_FILE 是服务帐号凭据 JSON 文件的路径。

    • APPLICATION 是正在运行并且连接了 Debugger 的.NET Core 应用的入口点。

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

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

控制台

要使用控制台启用 Debugger,请完成以下步骤:

  1. 选择集群类型后,点击节点池窗格中的更多选项

    节点池选项

  2. 安全性窗格中选择下列其中一项:

    • 允许所有 Cloud API 的全面访问权限

    • 允许每个 API 的访问权限,然后针对 Cloud Debugger 选择已启用

Debugger 现可用于您的应用。

要让 Cloud Console 中的“调试”页面可以自动显示与已部署应用匹配的源代码,请参阅自动选择源代码

Compute Engine

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

本地

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

  • GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为指向 JSON 服务帐号完整文件路径。
  • STACKDRIVER_DEBUGGER_MODULE 环境变量设置为要调试的组件的名称。此模块名称将会显示在允许调试的模块的 Cloud Console 列表中。
  • STACKDRIVER_DEBUGGER_VERSION 环境变量设置为要调试的模块的逻辑版本。这样便可在 Cloud Console 中调试模块的多个逻辑版本。
  • 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 构建时,变量可能被错误命名或丢失。