Note: Cloud Debugger is deprecated with a shutdown date of 31 May 2023. This repository is unsupported.

Stackdriver Debugger for .NET Core - Alpha

.NET Core Debugger for the Stackdriver Debugger.

Stackdriver Debugger is a feature of the Google Cloud Platform that lets you inspect the state of an application at any code location without using logging statements and without stopping or slowing down your applications.

Overview

The .NET Core Stackdriver Debugger is comprised of four major parts

• Debuggee - The Debuggee is the .NET Core application being debugged.
• Stackdriver Debugger - The Stackdriver Debugger is a web application that allows users to view source code and set snapshots on Debuggees.
• .NET Debugger - The .NET Core Debugger is an implementation of the ICorDebug interface used to debug the Debugee.
• Debugging Agent - The Debugging Agent will run alongside the .NET Core Debugger. It is responsible for starting the .NET Core Debugger as well as maintaining communication with the Stackdriver Debugger.

Docker Images

Prebuilt Ubuntu 16.04 (x64) Docker images are available for use. For detailed instructions see the Stackdriver Debugger documentation for .NET Core.

• gcr.io/dotnet-debugger/aspnetcore:1.0
• gcr.io/dotnet-debugger/aspnetcore:1.1
• gcr.io/dotnet-debugger/aspnetcore:2.0
• gcr.io/dotnet-debugger/aspnetcore:2.1

Usage

The .NET Core Stackdriver Debugger is currently in Alpha. This product might be changed in backward-incompatible ways and is not subject to any SLA or deprecation policy. It is not guaranteed to move forward to General Availability. This product is not intended for real-time usage in critical applications.

For detailed usage instructions see the official Stackdriver Debugger for .NET Core documentation.

To be able to use the .NET Core Stackdriver Debugger you will need to deploy PDBs with your code. See the example below:

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

Note: When debugging a Release build variables may be misnamed or missing.

Compatibility

This debugger has been tested with the following .NET Core versions:

• .NET Core 1.0.x
• .NET Core 1.1.x
• .NET Core 2.0.x

This debugger has been tested on the following runtimes:

• win-x64
• debian.8-x64
• ubuntu.16.04-x64

Building

Before building ensure you have all of the dependencies installed to build:

• dotnet/coreclr
• google/googletest
• google/protobuf

Linux

The repository and dependencies can be built with the following:

./build-deps.sh
./build.sh

Windows

The dependencies can be built with the following:

.\build-deps.cmd
.\build.sh

Running

Once the repository and dependencies are built you can run the debugger with:

Linux

dotnet ./Google.Cloud.Diagnostics.Debug/bin/Debug/netcoreapp2.0/Google.Cloud.Diagnostics.Debug.dll \
  --debugger=./google_cloud_debugger/google_cloud_debugger \
  --application-id=<Process ID of a running .NET Core application to debug> \
  --project-id=<Google Cloud Console project id> \
  --module=<Module of your application> \
  --version=<Version of your application>

Windows

dotnet .\Google.Cloud.Diagnostics.Debug\bin\Debug\netcoreapp2.0\Google.Cloud.Diagnostics.Debug.dll ^
  --debugger=.\x64\Debug\google_cloud_debugger.exe ^
  --application-id=<Process ID of a running .NET Core application to debug> ^
  --project-id=<Google Cloud Console project id> ^
  --module=<Module of your application> ^
  --version=<Version of your application>

Running Tests

Once the repository and dependencies are built you can run the tests with:

Unit Tests

./run_unit_tests.sh

Integration Tests

./run_integration_tests.sh

Performance Tests

./run_integration_tests.sh --performance-tests