Setting Up Cloud Debugger for .NET Core

Overview

This page describes how to configure your environment and your .NET Core application to use Cloud Debugger. For some environments, you must explicitly specify the access scope to let the Cloud Debugger agent send data. We recommend setting the broadest possible access scope and then using Identity and Access Management to restrict access. In keeping with this best practice, set the access scope to be all Cloud APIs with the option cloud-platform.

Language versions and compute environments

Cloud Debugger is available for .NET Core 1.0 through 2.1 on the following compute environments:

App Engine Standard environment	App Engine Flexible environment	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos	VMs and Containers running elsewhere	Cloud Functions

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Setting up Cloud Debugger

To set up Cloud Debugger, complete the following tasks:

1. Verify the Cloud Debugger API is enabled for your project.

2. Install and configure the Debugger on the compute environment you're using.

3. Select your source code.

Verifying the Cloud Debugger API is enabled

To begin using Cloud Debugger, ensure that the Cloud Debugger API is enabled. Cloud Debugger is enabled by default for most projects.
Enable Cloud Debugger API

Note: Cloud Debugger is free to use. However, you need a Google Cloud project with billing enabled before you can use Cloud Debugger.

App Engine standard environment

The Cloud Debugger agent for .NET Core isn't supported in App Engine standard environment.

App Engine flexible environment

1. Change the runtime in your app.yaml to custom:

   runtime: custom
   env: flex
   

2. Use a custom 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"]
   

   Where:

   • APPLICATION is the binary you wish to run and debug.

The Google Cloud's operations suite is now ready for use with your application.

To have the Debug page in the Google Cloud console automatically display source code matching the deployed application, see Selecting source code automatically.

Google Kubernetes Engine

GCLOUD

To enable Debugger using gcloud, complete the following steps:

1. Create your cluster with one of the following access scopes:

   • https://www.googleapis.com/auth/cloud-platform grants your cluster access to all Google Cloud APIs.

   • https://www.googleapis.com/auth/cloud_debugger grants your cluster access to only the Debugger API. Use this access scope to harden your cluster's security.

   gcloud container clusters create example-cluster-name \
          --scopes=https://www.googleapis.com/auth/cloud_debugger
   

   Note: You cannot change the access scopes of a cluster after creation.

2. Add the following lines to your Dockerfile to add the Debugger agent to your containerized app:

   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"]
   

   Where:

   • source-context.json is the JSON-formatted file containing your source context configuration. See Selecting source code automatically for information on generating this file.

   • MODULE is the name of the application. Together with version, it identifies the application in the Google Cloud console. Examples: MyApp,Backend, or Frontend.

   • VERSION is the application version (e.g., the build ID). The Google Cloud console displays the running application as MODULE - VERSION. Examples: v1.0, build_147, or v20160520.

   • CREDENTIALS_FILE is the path to the service account credentials JSON file.

   • APPLICATION is the entry point to the .NET Core application being run with Debugger attached.

The debugger is now ready for use when you deploy your containerized app.

For more detailed information on creating a cluster, see Creating a cluster.

CONSOLE

To enable Debugger by using the Google Cloud console, complete the following steps:

1. On the Node pools section, select Security, and then select Set access for each API.

2. Enable Debugger.

   

3. Optional: Select Allow full access to all Cloud APIs.

The debugger is now ready for use with your application.

To have the Debug page in the Google Cloud console automatically display source code matching the deployed application, see Selecting source code automatically.

Compute Engine

The Cloud Debugger agent for .NET Core isn't supported in Compute Engine environment.

Note: You can find the debugger agent's code and documentation on GitHub: agent.

Local

To use Google Cloud's operations suite while running your application locally:

• Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to service account json full file path.
• Set the STACKDRIVER_DEBUGGER_MODULE the environment variable to the name of component being debugged. This module name will appear in the Google Cloud console list of modules allowed to be debugged.
• Set STACKDRIVER_DEBUGGER_VERSION environment variable to the logical version of the module being debugged. This allows debugging multiple logical versions of the module in Google Cloud console.
• Set STACKDRIVER_DEBUGGER_DEBUGGER environment variable to point to a location of the Google Cloud's operations suite binary.
• If running on Linux, set LD_LIBRARY_PATH environment variable to include Google Cloud's operations suite directory.

When building the .NET Core application, include and deploy PDB files with your code. Include the following lines in each PDB file:

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

Note that when debugging a Release build, variables might be misnamed or missing.