Docker.DotNet 3.125.10

There is a newer version of this package available.
See the version list below for details.
dotnet add package Docker.DotNet --version 3.125.10                
NuGet\Install-Package Docker.DotNet -Version 3.125.10                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Docker.DotNet" Version="3.125.10" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Docker.DotNet --version 3.125.10                
#r "nuget: Docker.DotNet, 3.125.10"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Docker.DotNet as a Cake Addin
#addin nuget:?package=Docker.DotNet&version=3.125.10

// Install Docker.DotNet as a Cake Tool
#tool nuget:?package=Docker.DotNet&version=3.125.10                

.NET Client for Docker Remote API

This library allows you to interact with Docker Remote API endpoints in your .NET applications.

It is fully asynchronous, designed to be non-blocking and object-oriented way to interact with your Docker daemon programmatically.

Versioning

Version of this package uses SemVer format: MAJOR.MINOR.PATCH. MINOR segment indicates the Docker Remote API version support. For instance v2.124.0 of this library supports Docker Remote API v1.24. This does not guarantee backwards compatibility as Docker Remote API does not guarantee that either.

MAJOR is reserved for major breaking changes we make to the library itself such as how the calls are made or how authentication is made. PATCH is just for incremental bug fixes or non-breaking feature additions.

Installation

NuGet latest release

You can add this library to your project using NuGet.

Package Manager Console Run the following command in the “Package Manager Console”:

PM> Install-Package Docker.DotNet

Visual Studio Right click to your project in Visual Studio, choose “Manage NuGet Packages” and search for ‘Docker.DotNet’ and click ‘Install’. (see NuGet Gallery.)

.NET Core Command Line Interface Run the following command from your favorite shell or terminal:

dotnet add package Docker.DotNet

Development Builds

alternate text is missing from this package README image

If you intend to use development builds of Docker.DotNet and don't want to compile the code yourself you can add the package source below to Visual Studio or your Nuget.Config.

https://ci.appveyor.com/nuget/docker-dotnet-hojfmn6hoed7

Usage

You can initialize the client like the following:

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

or to connect to your local Docker for Windows daemon using named pipes or your local Docker for Mac daemon using Unix sockets:

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

For a custom endpoint, you can also pass a named pipe or a Unix socket to the DockerClientConfiguration constructor. For example:

// Default Docker Engine on Windows
using Docker.DotNet;
DockerClient client = new DockerClientConfiguration(
    new Uri("npipe://./pipe/docker_engine"))
     .CreateClient();
// Default Docker Engine on Linux
using Docker.DotNet;
DockerClient client = new DockerClientConfiguration(
    new Uri("unix:///var/run/docker.sock"))
     .CreateClient();
Example: List containers
IList<ContainerListResponse> containers = await client.Containers.ListContainersAsync(
	new ContainersListParameters(){
		Limit = 10,
    });
Example: Create an image by pulling from Docker Registry

The code below pulls fedora/memcached image to your Docker instance using your Docker Hub account. You can anonymously download the image as well by passing null instead of AuthConfig object:

await client.Images.CreateImageAsync(
    new ImagesCreateParameters
    {
        FromImage = "fedora/memcached",
        Tag = "alpha",
    },
    new AuthConfig
    {
        Email = "test@example.com",
        Username = "test",
        Password = "pa$$w0rd"
    },
    new Progress<JSONMessage>());
Example: Create a container

The following code will create a new container of the previously fetched image.

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

The following code will start the created container.

await client.Containers.StartContainerAsync(
    "39e3317fd258",
    new ContainerStartParameters()
    );
Example: Stop a container

The following code will stop a running container.

Note: WaitBeforeKillSeconds field is of type uint? which means optional. This code will wait 30 seconds before killing it. If you like to cancel the waiting, you can use the CancellationToken parameter.

var stopped = await client.Containers.StopContainerAsync(
    "39e3317fd258",
    new ContainerStopParameters
    {
        WaitBeforeKillSeconds = 30
    },
    CancellationToken.None);
Example: Dealing with Stream responses

Some Docker API endpoints are designed to return stream responses. For example Monitoring Docker events continuously streams the status in a format like :

{"status":"create","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
{"status":"start","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
{"status":"stop","id":"dfdf82bd3881","from":"base:latest","time":1374067966}
{"status":"destroy","id":"dfdf82bd3881","from":"base:latest","time":1374067970}
...

To obtain this stream you can use:

CancellationTokenSource cancellation = new CancellationTokenSource();
Stream stream = await client.System.MonitorEventsAsync(new ContainerEventsParameters(), new Progress<JSONMessage>(), cancellation.Token);
// Initialize a StreamReader...

You can cancel streaming using the CancellationToken. On the other hand, if you wish to continuously stream, you can simply pass CancellationToken.None.

Example: HTTPS Authentication to Docker

If you are running Docker with TLS (HTTPS), you can authenticate to the Docker instance using the Docker.DotNet.X509 package. You can get this package from NuGet or by running the following command in the “Package Manager Console”:

PM> Install-Package Docker.DotNet.X509

Once you add Docker.DotNet.X509 to your project, use CertificateCredentials type:

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

If you don't want to authenticate you can omit the credentials parameter, which defaults to an AnonymousCredentials instance.

The CertFile in the example above should be a .pfx file (PKCS12 format), if you have .pem formatted certificates which Docker normally uses you can either convert it programmatically or use openssl tool to generate a .pfx:

openssl pkcs12 -export -inkey key.pem -in cert.pem -out key.pfx

(Here, your private key is key.pem, public key is cert.pem and output file is named key.pfx.) This will prompt a password for PFX file and then you can use this PFX file on Windows. If the certificate is self-signed, your application may reject the server certificate, in this case you might want to disable server certificate validation:

//
// There are two options to do this.
//

// You can do this globally for all certificates:
// (Note: This is not available on netstandard1.6)
ServicePointManager.ServerCertificateValidationCallback += (o, c, ch, er) => true;

// Or you can do this on a credential by credential basis:
var creds = new CertificateCredentials(...);
creds.ServerCertificateValidationCallback += (o, c, ch, er) => true;

Example: Basic HTTP Authentication to Docker

If the Docker instance is secured with Basic HTTP Authentication, you can use the Docker.DotNet.BasicAuth package. Get this package from NuGet or by running the following command in the “Package Manager Console”:

PM> Install-Package Docker.DotNet.BasicAuth

Once you added Docker.DotNet.BasicAuth to your project, use BasicAuthCredentials type:

var credentials = new BasicAuthCredentials ("YOUR_USERNAME", "YOUR_PASSWORD");
var config = new DockerClientConfiguration("tcp://ubuntu-docker.cloudapp.net:4243", credentials);
DockerClient client = config.CreateClient();

BasicAuthCredentials also accepts SecureString for username and password arguments.

Example: Specifying Remote API Version

By default this client does not specify version number to the API for the requests it makes. However, if you would like to make use of versioning feature of Docker Remote API You can initialize the client like the following.

var config = new DockerClientConfiguration(...);
DockerClient client = config.CreateClient(new Version(1, 16));

Error Handling

Here are typical exceptions thrown from the client library:

  • DockerApiException is thrown when Docker API responds with a non-success result. Subclasses:
    • DockerContainerNotFoundException
    • DockerImageNotFoundException
  • TaskCanceledException is thrown from System.Net.Http.HttpClient library by design. It is not a friendly exception, but it indicates your request has timed out. (default request timeout is 100 seconds.)
    • Long-running methods (e.g. WaitContainerAsync, StopContainerAsync) and methods that return Stream (e.g. CreateImageAsync, GetContainerLogsAsync) have timeout value overridden with infinite timespan by this library.
  • ArgumentNullException is thrown when one of the required parameters are missing/empty.
    • Consider reading the Docker Remote API reference and source code of the corresponding method you are going to use in from this library. This way you can easily find out which parameters are required and their format.

.NET Foundation

Docker.DotNet is a .NET Foundation project.

There are many .NET related projects on GitHub.

  • .NET home repo - links to 100s of .NET projects, from Microsoft and the community.
  • ASP.NET Core home - the best place to start learning about ASP.NET Core.

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information, see the .NET Foundation Code of Conduct.

General .NET OSS discussions: .NET Foundation forums

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.dotnetfoundation.org.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

License

Docker.DotNet is licensed under the MIT license.


Copyright (c) .NET Foundation and Contributors

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (84)

Showing the top 5 NuGet packages that depend on Docker.DotNet:

Package Downloads
Testcontainers

Testcontainers for .NET is a library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions.

Docker.DotNet.X509

Docker.DotNet.X509 is a library that allows you to use certificate authentication with a remote Docker engine programmatically in your .NET applications.

DotNet.Testcontainers

A lightweight library to run tests with throwaway instances of Docker containers.

Docker.DotNet.BasicAuth

Docker.DotNet.BasicAuth is a library that allows you to use basic authentication with a remote Docker engine programmatically in your .NET applications.

Squadron.Core

Package Description

GitHub repositories (31)

Showing the top 5 popular GitHub repositories that depend on Docker.DotNet:

Repository Stars
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
danielgerlag/workflow-core
Lightweight workflow engine for .NET Standard
dotnetcore/DotnetSpider
DotnetSpider, a .NET standard web crawling library. It is lightweight, efficient and fast high-level web crawling & scraping framework
testcontainers/testcontainers-dotnet
A library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions.
EasyNetQ/EasyNetQ
An easy to use .NET API for RabbitMQ
Version Downloads Last updated
3.125.15 14,621,770 5/18/2023
3.125.14 227,586 4/14/2023
3.125.13 1,329,401 3/1/2023
3.125.12 3,726,728 9/18/2022
3.125.11 76,572 9/3/2022
3.125.10 1,740,709 7/19/2022
3.125.5 2,458,803 8/31/2021
3.125.4 3,364,202 8/12/2020
3.125.2 4,134,950 4/17/2018
3.125.1 49,754 1/31/2018
3.125.0 169,216 7/27/2017
2.124.3 110,151 10/17/2016
2.124.1 5,103 7/15/2016
1.2.2 12,226 12/31/2015
1.2.1 3,044 11/25/2015
1.2.0 4,340 9/17/2015
1.1.2.1 2,579 8/21/2015
1.1.1 2,809 10/10/2014
1.1.0 3,949 9/26/2014
1.0.0 6,902 9/15/2014
1.0.0-beta 2,544 9/5/2014