Docker.DotNet

The SpecGen tool generates C# models that combine both QueryString parameters and JSON body models into a single object. This design simplifies the calling API by allowing a single parameter object to represent all data required for a remote API call.

Query String Parameters

Parameters intended for the URL query string are decorated with [QueryStringParameter]. To handle optionality, the tool uses nullable types (e.g., bool?). This allows the client to distinguish between a parameter being absent versus being explicitly set to a default value like false.

Example of a model with query string parameters:

[DataContract]
public class ContainerAttachParameters
{
    [QueryStringParameter("stream", false, typeof(BoolQueryStringConverter))]
    public bool? Stream { get; set; }

    [QueryStringParameter("stdin", false, typeof(BoolQueryStringConverter))]
    public bool? Stdin { get; set; }
}

JSON Body Parameters

Parameters intended for the request body are decorated with [DataMember]. The EmitDefaultValue = false setting ensures that if a property's value matches its C# default value, it is omitted from the resulting JSON payload, preventing unnecessary data from being sent to the Docker engine.

Example of a model with JSON body parameters:

[DataContract]
public class Config
{
    [DataMember(Name = "Hostname", EmitDefaultValue = false)]
    public string Hostname { get; set; }

    [DataMember(Name = "Domainname", EmitDefaultValue = false)]
    public string Domainname { get; set; }
}

Customizations (Enums and Types)

SpecGen allows for custom serialization logic to improve API usability. For example, it can map integer values from the engine-api to strongly-typed C# enums. This is achieved via a typeCustomizations map within the tool's source code (specgen.go).

using System.Runtime.Serialization;

namespace Docker.DotNet.Models
{
    [DataContract]
    public class ContainerAttachParameters
    {
        [QueryStringParameter("stream", false, typeof(BoolQueryStringConverter))]
        public bool? Stream { get; set; }

        [QueryStringParameter("stdin", false, typeof(BoolQueryStringConverter))]
        public bool? Stdin { get; set; }
    }
}

Use the client.Containers property to perform lifecycle operations on containers.

List containers

IList<ContainerListResponse> containers = await client.Containers.ListContainersAsync(
    new ContainersListParameters() {
        Limit = 10,
    });

Create a container

await client.Containers.CreateContainerAsync(new CreateContainerParameters()
    {
        Image = "fedora/memcached",
        HostConfig = new HostConfig()
        {
            DNS = new[] { "8.8.8.8", "8.8.4.4" }
        }
    });

Start a container

await client.Containers.StartContainerAsync(
    "39e3317fd258",
    new ContainerStartParameters()
    );

Stop a container

Note: WaitBeforeKillSeconds is an optional uint?. This example waits 30 seconds before killing the container.

var stopped = await client.Containers.StopContainerAsync(
    "39e3317fd258",
    new ContainerStopParameters
    {
        WaitBeforeKillSeconds = 30
    },
    CancellationToken.None);

IList<ContainerListResponse> containers = await client.Containers.ListContainersAsync(
	new ContainersListParameters(){
		Limit = 10,
    });

The DockerClient is the primary entry point for interacting with the Docker daemon. You initialize it using DockerClientConfiguration.

Connect to a remote endpoint via URI

using Docker.DotNet;
DockerClient client = new DockerClientConfiguration(
    new Uri("http://ubuntu-docker.cloudapp.net:4243"))
     .CreateClient();

Connect to local Docker (Windows/Mac)

For local daemons using named pipes (Windows) or Unix sockets (Mac), use the parameterless constructor:

using Docker.DotNet;
DockerClient client = new DockerClientConfiguration()
     .CreateClient();

Connect using specific protocols (Named Pipes or Unix Sockets)

// Windows Named Pipe
using Docker.DotNet;
DockerClient client = new DockerClientConfiguration(
    new Uri("npipe://./pipe/docker_engine"))
     .CreateClient();

// Linux Unix Socket
using Docker.DotNet;
DockerClient client = new DockerClientConfiguration(
    new Uri("unix:///var/run/docker.sock"))
     .CreateClient();

To connect to a Docker instance running with TLS, use the Docker.DotNet.X509 package and the CertificateCredentials type.

Setup

Install the X509 package:

Install-Package Docker.DotNet.X509

Usage

var credentials = new CertificateCredentials (new X509Certificate2 ("CertFile", "Password"));
var config = new DockerClientConfiguration("http://ubuntu-docker.cloudapp.net:4243", credentials);
DockerClient client = config.CreateClient();

Handling Self-Signed Certificates

If the server certificate is self-signed, you can disable validation globally or per credential:

Globally:

ServicePointManager.ServerCertificateValidationCallback += (o, c, ch, er) => true;

Per Credential:

var creds = new CertificateCredentials(...);
creds.ServerCertificateValidationCallback += (o, c, ch, er) => true;

Note: CertFile should be a .pfx (PKCS12) file. If you have .pem files, convert them using openssl.