Cross-Platform Core Dump Analysis: Debugging ASP.NET Core with Docker

Table of Contents

Debugging production issues in modern cross-platform applications can present unique challenges. When an application crashes or hangs, capturing a core dump provides a snapshot of the process’s memory at that specific moment. Analyzing these dumps is crucial for understanding the root cause of the failure, but it often requires a compatible environment, particularly concerning the operating system and architecture where the dump was generated.

This article outlines a robust method for analyzing .NET Core core dump files captured on a Linux environment, specifically focusing on how to open and inspect them from a Windows machine using Docker. This approach leverages the portability of containers to create the necessary Linux analysis environment seamlessly. We will cover the preparation steps, including obtaining the core dump and setting up your Windows machine with Docker Desktop. This method applies to applications targeting .NET Core 2.1, .NET Core 3.1, and .NET 5.

The primary goal of this guide is to equip you with the knowledge and steps required to effectively analyze a Linux-generated .NET Core core dump file using tooling within a Docker container, all while working from a Windows operating system. This technique allows developers and support engineers to debug issues that occur on Linux servers without needing a dedicated Linux analysis environment or transferring large system files. By the end of this process, you will be able to load the dump file into the dotnet-dump analysis tool running inside a Docker container and begin investigating the application’s state at the time of the crash.

Understanding Core Dumps and Cross-Platform Challenges¶

A core dump is essentially a file containing the memory image of a running process when it terminates unexpectedly or encounters a critical error. For .NET Core applications running on Linux, these dumps are typically generated by the operating system (e.g., using gcore or automatically configured via /proc/sys/kernel/core_pattern). Analyzing these dumps allows developers to inspect the managed heap, thread stacks, object states, and other critical runtime information using specialized debugger tools.

The main challenge in analyzing a core dump lies in matching the analysis environment to the environment where the dump was created. This includes using the correct versions of the .NET runtime, debugging tools, and symbols that correspond to the application and environment at the time of the dump. Analyzing a dump generated on a Linux distribution from a Windows machine directly is not feasible due to operating system differences and tool compatibility. Historically, this required setting up a identical Linux VM or transferring the dump to a compatible Linux machine for analysis.

Docker provides an elegant solution to this problem. By packaging the necessary Linux operating system, the .NET runtime, and the required debugging tools into a self-contained container image, we can create a consistent and reproducible analysis environment on demand. This eliminates the need for dedicated Linux VMs for analysis purposes and simplifies the setup process significantly. The dump file itself can be mounted into the container or included during the container build process, making it available for analysis within the isolated environment.

Introducing Containers and Docker for Debugging¶

Containers are a lightweight, portable, and self-sufficient way to package software and its dependencies. They abstract away the underlying infrastructure, ensuring that an application runs consistently across different computing environments, whether it’s a developer’s laptop, a test server, or a production cloud environment. Docker is a popular platform for building, distributing, and running these containerized applications.

A Docker container image is a static snapshot of a container, containing the application code, runtime, libraries, and settings. A container is a running instance of an image. For our purpose, we will build a Docker image that includes a Linux operating system, the .NET SDK, and the necessary debugging tools like dotnet-dump and dotnet-symbol. This image will then be used to launch a container where we can perform our dump analysis.

To use Docker containers on a Windows machine, you need to install Docker Desktop for Windows. Docker Desktop integrates with Windows Subsystem for Linux (WSL) to run Linux containers efficiently. It’s important to note that Docker Desktop can run either Windows containers or Linux containers, but not both simultaneously. For analyzing Linux core dumps, you must ensure Docker Desktop is configured to use Linux containers. Before proceeding, ensure Docker Desktop is installed and running, and that it’s switched to Linux container mode.

Preparing the Analysis Environment: The Dockerfile¶

The heart of creating our reproducible analysis environment is the dockerfile. A dockerfile is a text file that contains a series of instructions that Docker uses to build an image. Each instruction creates a layer in the image, making the build process efficient and allowing for caching. The filename must be exactly dockerfile (all lowercase, no extension) when placed in the build context directory.

The instructions within the dockerfile specify the base image, install software, set environment variables, copy files, and configure the container. We will use a multi-stage build to keep the final image size manageable and ensure we have access to the .NET SDK for installing global tools. Comments, starting with #, can be added to explain each step, which is good practice for clarity.

Let’s break down a typical dockerfile tailored for .NET Core dump analysis:

# Stage 1: Install the latest Ubuntu base image.
# This provides the foundational Linux environment.
FROM ubuntu:latest

# Stage 2: Use a .NET SDK image to install tools.
# We use the SDK image specifically because dotnet tool install
# requires the SDK to be present.
FROM mcr.microsoft.com/dotnet/core/sdk:latest AS tools-install

# Update and upgrade the base OS packages within the SDK stage.
# This ensures we have the latest security patches and dependencies.
# The trailing backslash (\) allows the command to span multiple lines.
RUN apt-get update \
    && apt-get upgrade -y \
    && apt-get install -y

# Install the .NET diagnostic tools globally using the dotnet tool command.
# dotnet-dump is used for interactive core dump analysis.
# dotnet-symbol is used to download required debugging symbols and DAC/DBI files.
# We install them to a specific directory /dotnetcore-tools.
RUN dotnet tool install --tool-path /dotnetcore-tools dotnet-dump
RUN dotnet tool install --tool-path /dotnetcore-tools dotnet-symbol

# Add the directory containing the installed tools to the PATH environment variable.
# This allows us to run dotnet-dump and dotnet-symbol from any location in the container shell.
ENV PATH="/dotnetcore-tools:${PATH}"

# Stage 3: Switch back to the base Ubuntu image for the final analysis environment.
# This helps keep the final image smaller by not including the full SDK,
# only the necessary runtime components and tools installed in Stage 2.
FROM ubuntu:latest

# Copy the tools installed in the previous stage into the final image.
# This takes the results of the 'tools-install' stage and copies them over.
COPY --from=tools-install /dotnetcore-tools /dotnetcore-tools

# Ensure the tools directory is in the PATH in this final image as well.
ENV PATH="/dotnetcore-tools:${PATH}"

# Create a directory inside the container where the core dump files will be placed.
# This provides a designated and known location for accessing the dumps.
RUN mkdir /dumps

# Copy the compressed core dump file from the host (Windows VM) into the container's /dumps directory.
# This assumes you have packaged your core dumps into a coredumps.tar.gz file
# in the same directory as the dockerfile on your Windows host.
COPY ./coredumps.tar.gz /dumps/

# Extract the contents of the tar.gz file into the /dumps directory within the container.
# The -C flag specifies the target directory for extraction.
RUN tar -xf /dumps/coredumps.tar.gz -C /dumps

# Run dotnet-symbol on one of the core dump files.
# This command downloads necessary debugging files (symbols, DAC, DBI) for the specific .NET runtime version
# used by the dumped process. --host-only is often used for specific scenarios,
# while --debugging targets files needed for debugging itself.
# The path ~/dumps/coredump.manual.1.11724 is an example; replace with your dump file name.
# Note: Running this during the build ensures symbols are ready upon entering the container.
RUN dotnet-symbol --host-only --debugging /dumps/coredump.manual.1.11724

Place this dockerfile in the same directory on your Windows machine where you have copied the coredumps.tar.gz file containing your Linux core dumps. Remember the strict naming convention: dockerfile. This file acts as the blueprint for your portable debugging environment.

Building and Running the Container¶

With the dockerfile and the compressed dump file in place, the next step is to build the Docker image and run a container from it. Open a Command Prompt or PowerShell window in the directory containing your dockerfile and coredumps.tar.gz.

First, build the Docker image using the docker build command. The -t flag tags the image with a name (here, dotnettools) and optionally a tag (defaults to latest). The . at the end specifies the build context – meaning Docker should look for the dockerfile and other files in the current directory.

docker build -t dotnettools .

Docker will execute the instructions in the dockerfile step by step. For the first build, this process will involve downloading the base Ubuntu and .NET SDK images, installing packages, and downloading symbols, which might take some time depending on your internet connection. Subsequent builds will be significantly faster due to Docker’s caching mechanism; it only rebuilds layers that have changed.

Once the build is complete, you can verify the image exists by running docker images. You should see dotnettools in the list.

Now, launch a container from the newly built image using the docker container run command.
* The -it flags allocate a pseudo-TTY (-t) and keep STDIN open (-i), allowing you to interact with the container’s shell.
* dotnettools is the name of the image we want to run.
* /bin/bash is the command to execute inside the container – in this case, starting the Bash shell, which drops you into an interactive terminal session.

docker container run -it dotnettools /bin/bash

After running this command, your terminal prompt will change, indicating that you are now inside the running Linux container. You have successfully entered your portable, pre-configured analysis environment.

Analyzing the Core Dump¶

Inside the container, you can navigate the file system just like on any Linux machine. The core dump files are located in the /dumps directory, as specified in the dockerfile. The dotnet-dump and dotnet-symbol tools are available directly from the command line because their directory was added to the PATH environment variable.

To begin the analysis, use the dotnet-dump analyze command, providing the full path to the core dump file you wish to inspect. Replace /dumps/coredump.manual.1.11724 with the actual filename of your dump within the /dumps directory.

dotnet-dump analyze /dumps/coredump.manual.1.11724

This command loads the core dump into the interactive dotnet-dump analysis environment. The prompt will change to >. You can now execute various debugger commands, including SOS (Son of Strike) commands, which are specifically designed for debugging .NET applications.

Here are some essential SOS commands you can use within the dotnet-dump analyzer:

Command	Description	Example Usage
clrthreads	Lists the managed threads in the process.	clrthreads
dumpheap	Displays information about the garbage-collected heap, including object types and counts.	dumpheap -stat
clrobjects	Displays object types and counts, similar to dumpheap -stat.	clrobjects
pe <address>	Displays information about a managed object at a specific memory address.	pe 0x123abc
dumpvc <address>	Displays information about a value type instance.	dumpvc 0x456def
dso	Displays managed objects currently on the stack.	dso
gcroot <address>	Displays garbage collection roots for an object.	gcroot 0x123abc
dumpmd <address>	Displays metadata for a MethodDesc pointer.	dumpmd 0x7f1234567890
eeheap	Displays information about process memory used by the CLR.	eeheap -gc
help	Displays a list of available commands or help for a specific command.	help dumpheap
exit	Exits the dotnet-dump analysis session.	exit

For example, running clrthreads will show you the state of all managed threads at the time the dump was taken, which is invaluable for debugging hangs or deadlocks.

> clrthreads
ThreadCount: 15
OSID           ManagedThreadID State       GC Mode     Profiler State  Fault      Lock Count
0x1d6          1               Unknown     Preemptive  None            None       0
0x1f8          2               Waiting     Preemptive  None            None       0
0x1fa          3               Waiting     Preemptive  None            None       0
...

You can then use the OSID or ManagedThreadID with other commands if they support it, or simply inspect the state of threads that appear problematic. Exploring the heap using dumpheap or clrobjects helps identify memory pressure or unexpected object allocations.

Benefits of Using Docker for Dump Analysis¶

This Docker-based approach offers several significant advantages for cross-platform .NET Core dump analysis:

1. Environmental Isolation and Consistency: The container provides a clean, isolated environment with the exact dependencies (OS distribution, .NET runtime, tools) needed for analysis, preventing conflicts with your host system.
2. Reproducibility: The dockerfile serves as a script to recreate the analysis environment. Anyone with Docker can build the same image, ensuring consistent analysis setups across teams.
3. Portability: The analysis environment is packaged into an image that can be easily shared. The dump file is simply copied in.
4. Simplified Setup on Windows: Instead of setting up a full Linux VM with all dependencies from scratch, you only need Docker Desktop and the dockerfile.
5. Efficiency: Docker layers and caching make subsequent builds faster.

Conclusion¶

Debugging core dumps from ASP.NET Core applications running on Linux doesn’t have to be a cumbersome process when working from a Windows machine. By leveraging Docker, you can create a portable, consistent, and isolated Linux environment specifically tailored for dump analysis. The dockerfile acts as your blueprint, automating the setup of the operating system, .NET tools, and the preparation of the dump files.

Once inside the Docker container, the familiar dotnet-dump and SOS commands are at your disposal, allowing you to perform in-depth debugging of managed code, inspect the heap, examine threads, and ultimately diagnose the issues that led to the core dump. This method streamlines the cross-platform debugging workflow, making it more efficient and accessible for developers and support engineers alike. Embrace the power of containerization to simplify your debugging efforts.

Have you used Docker for debugging or other cross-platform development tasks? What are your favorite dotnet-dump or SOS commands for analyzing core dumps? Share your experiences and insights in the comments below!