What is Docker.NET?

Docker.NET is a powerful, open-source .NET client library that provides a programmatic interface to communicate with the Docker Engine API using C# or any other .NET-compatible language. It allows developers to interact with Docker containers, images, volumes, and networks directly within their .NET applications, automating container lifecycle management and extending Docker’s capabilities into the .NET ecosystem.

Originally developed to bridge the gap between Docker and the .NET platform, Docker.NET enables scenarios like creating, starting, stopping, inspecting, or deleting containers without relying on CLI commands or external scripts. It plays a critical role in modern DevOps and microservices workflows where container automation is key.

Major Use Cases of Docker.NET

1. DevOps Automation:
   Automate Docker workflows such as building images, deploying containers, or managing volumes in a CI/CD pipeline using .NET.
2. Container Orchestration Tools:
   Build custom container management tools or lightweight orchestrators in .NET to manage Docker on local or remote hosts.
3. Microservices Deployment:
   Launch, monitor, and manage microservices inside Docker containers using .NET-based service controllers.
4. Testing & Simulation Environments:
   Automate the spinning up of mock environments (e.g., databases, services) using containers for unit and integration testing.
5. Self-Healing Infrastructure:
   Monitor and auto-restart failed containers within a .NET background service or Windows service.
6. Cloud-Native Applications:
   Integrate with cloud-native toolchains or Kubernetes environments where Docker is a fundamental component.

How Docker.NET Works – Architecture Overview

Docker.NET acts as a client library that communicates with the Docker Engine API via HTTP over a Unix socket or named pipe (Windows). It sends JSON-based API requests that Docker understands and translates into operations like container creation or image pulling.

Architecture Components:

• Your .NET Application – Uses Docker.NET library via NuGet.
• Docker.NET Client – Converts high-level method calls (e.g., CreateContainerAsync) into HTTP requests.
• Docker Engine API – Receives requests and interacts with the Docker daemon.
• Docker Daemon – Performs the actual work like creating containers, managing volumes, or fetching logs.

[.NET App] → [DockerClient (Docker.NET)] → [Docker Engine API] → [Docker Daemon] → Containers/Images

This model ensures you don’t need to shell out to the CLI or use OS-dependent tools—just pure C# code.

Basic Workflow of Docker.NET

Here’s a generalized workflow when using Docker.NET:

1. Connect to Docker Engine:
   Instantiate a DockerClientConfiguration to connect to the Docker engine.
2. Create a Container:
   Define container parameters (image, ports, volumes, etc.) and use Containers.CreateContainerAsync.
3. Start the Container:
   Use Containers.StartContainerAsync to launch the container.
4. Monitor Logs / Stats:
   Stream container logs or stats using Containers.GetContainerLogsAsync or Containers.GetContainerStatsAsync.
5. Stop & Remove Container:
   Clean up using Containers.StopContainerAsync and Containers.RemoveContainerAsync.
6. Manage Images, Volumes, Networks:
   Pull or build images, create volumes, and manage networks using respective APIs.

Step-by-Step Getting Started Guide for Docker.NET

✅ Prerequisites

• Docker installed and running (Windows, Linux, or macOS)
• .NET 6.0 SDK or later
• Visual Studio or VS Code
• Internet access (to pull images from Docker Hub)

Step 1: Create a .NET Console App

dotnet new console -n DockerNetSample
cd DockerNetSample

Step 2: Add Docker.DotNet NuGet Package

dotnet add package Docker.DotNet

Step 3: Initialize Docker Client

using Docker.DotNet;
using Docker.DotNet.Models;

var config = new DockerClientConfiguration(
    new Uri("npipe://./pipe/docker_engine")); // For Windows
    // For Linux/macOS use: new Uri("unix:///var/run/docker.sock")

var client = config.CreateClient();

Step 4: Pull an Image (e.g., nginx)

await client.Images.CreateImageAsync(
    new ImagesCreateParameters { FromImage = "nginx", Tag = "latest" },
    null,
    new Progress<JSONMessage>(msg => Console.WriteLine(msg.Status)));

Step 5: Create and Start a Container

var response = await client.Containers.CreateContainerAsync(new CreateContainerParameters
{
    Image = "nginx",
    Name = "my-nginx",
    HostConfig = new HostConfig
    {
        PortBindings = new Dictionary<string, IList<PortBinding>>
        {
            { "80/tcp", new List<PortBinding> { new PortBinding { HostPort = "8080" } } }
        }
    }
});

await client.Containers.StartContainerAsync(response.ID, null);
Console.WriteLine($"Container started with ID: {response.ID}");

Step 6: Stop and Remove the Container

await client.Containers.StopContainerAsync("my-nginx", new ContainerStopParameters());
await client.Containers.RemoveContainerAsync("my-nginx", new ContainerRemoveParameters());