Docker.DotNet 3.125.15

Docker Remote API 的 .NET 客户端

此库允许您在 .NET 应用程序中与 Docker Remote API 端点交互。

它是完全异步的，旨在以非阻塞和面向对象的方式与 Dockerdaemon 进行程序性交互。

版本

此代码包版本采用 SemVer 格式：MAJOR.MINOR.PATCH。 MINOR 段表示支持的 Docker Remote API 版本。例如，此库的 v2.124.0 版本支持 Docker Remote API 版本 v1.24。这并不保证向下兼容性，因为 Docker Remote API 也不保证。

MAJOR 保留用于我们对其自身代码库进行的重大更改，例如调用方式或身份验证方式。 PATCH 只用于增量错误修复或非破坏性功能添加。

安装

您可以使用 NuGet 将此代码包添加到您的项目中。

包管理器控制台 在“包管理器控制台”中运行以下命令

PM> Install-Package Docker.DotNet

Visual Studio 在 Visual Studio 中右键单击您的项目，选择“管理 NuGet 包”，搜索“Docker.DotNet”并单击“安装”。 (查看 NuGet 代码包库)

.NET Core 命令行界面 请从您喜欢的 Shell 或终端运行以下命令

dotnet add package Docker.DotNet

开发构建

如果您打算使用 Docker.DotNet 的开发构建，但不希望自行编译代码，您可以将以下包源添加到 Visual Studio 或您的 Nuget.Config----

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

用法

您可以初始化客户端，如下所示

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

或连接到您本地的 Docker for Windows 守护进程，使用命名管道或您的本地 Docker for Mac 守护进程，使用 Unix 套接字

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

对于自定义端点，您还可以将命名管道或将 Unix 套接字传递给 DockerClientConfiguration 构造函数。例如

// 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();

示例：列出容器

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

示例：通过从 Docker 仓库拉取来创建镜像

以下代码将 fedora/memcached 镜像从您的 Docker 仓库拉取到您的 Docker 实例中。您还可以通过传递 AuthConfig 对象的替代 null 来匿名下载镜像

await client.Images.CreateImageAsync(
    new ImagesCreateParameters
    {
        FromImage = "fedora/memcached",
        Tag = "alpha",
    },
    new AuthConfig
    {
        Email = "[email protected]",
        Username = "test",
        Password = "pa$$w0rd"
    },
    new Progress<JSONMessage>());

示例：创建容器

以下代码将创建之前获取的镜像的新容器。

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

示例：启动容器

以下代码将启动创建的容器。

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

示例：停止容器

以下代码将停止运行的容器。

注意：WaitBeforeKillSeconds 字段是 uint? 类型，表示可选的。这段代码将在杀死之前等待 30 秒。如果您想取消等待，则可以使用 CancellationToken 参数。

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

示例：处理流响应

有些 Docker API 端点设计为返回流响应。例如 监控 Docker 事件 会持续以类似以下格式的格式传输状态：

{"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}
...

要获取此流，您可以使用

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

您可以使用 CancellationToken 取消流。另一方面，如果您希望持续流，只需传递 CancellationToken.None 即可。

示例：对 Docker 进行 HTTPS 身份验证

如果您正在使用 具有 TLS 的 Docker（HTTPS），您可以使用 Docker.DotNet.X509 包对 Docker 实例进行身份验证。您可以从 NuGet 或在“包管理器控制台”中运行以下命令来获取此包：

PM> Install-Package Docker.DotNet.X509

将 Docker.DotNet.X509 添加到您的项目后，使用 CertificateCredentials 类型

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

如果您不需要身份验证，可以省略 credentials 参数，它默认为 AnonymousCredentials 实例。

示例中上面的 CertFile 应该是 .pfx 文件（PKCS12 格式），如果您使用 Docker 正常使用的 .pem 格式的证书，您可以程序化地进行转换或使用 openssl 工具生成 .pfx。这样就提示 PFX 文件的密码，然后您可以在 Windows 上使用此 PFX 文件。如果证书是自签名的，则您的应用程序可能会拒绝服务器证书，在这种情况下，您可能想禁用服务器证书验证

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

（在这里，您的私钥是 key.pem，公钥是 cert.pem，输出文件名为 key.pfx。）

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

// You can do this globally for all certificates:
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;

示例：对 Docker 进行基本 HTTP 身份验证

如果 Docker 实例使用基本 HTTP 身份验证进行保护，您可以使用 Docker.DotNet.BasicAuth 包。您可以从 NuGet 或在“包管理器控制台”中运行以下命令来获取此包：

PM> Install-Package Docker.DotNet.BasicAuth

一旦将 Docker.DotNet.BasicAuth 添加到您的项目中，请使用 BasicAuthCredentials 类型。

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

BasicAuthCredentials 还接受用于用户名和密码参数的 SecureString。

示例：指定远程 API 版本

默认情况下，此客户端在发出的请求中不指定 API 版本号。但是，如果您想使用 Docker 远程 API 的版本特性，可以像下面这样初始化客户端。

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

错误处理

以下是客户端库抛出的典型异常。

• DockerApiException 当 Docker API 返回非成功结果时会抛出。子类包括：
  • DockerContainerNotFoundException
  • DockerImageNotFoundException
• TaskCanceledException 由 System.Net.Http.HttpClient 库设计抛出。它不是一个友好的异常，但它表明您的请求已超时。（默认请求超时时间为 100 秒。）
  • 长时间运行的方法（例如 WaitContainerAsync，StopContainerAsync）以及返回 Stream 的方法（例如 CreateImageAsync，GetContainerLogsAsync）此库将以无限时间间隔覆盖其超时值。
• ArgumentNullException 当缺少或为空必要的参数之一时抛出。
  • 考虑阅读 Docker 远程 API 参考 和您打算从本库中使用的相应方法的源代码。这样，您可以轻松地找到所需的参数及其格式。

.NET 基金会

Docker.DotNet 是一个 .NET Foundation 项目。

GitHub 上有许多 .NET 相关的项目。

• .NET 主目录仓库 - 提供了数百个 .NET 项目，来自微软和社区。
• ASP.NET Core 主页 - 学习 ASP.NET Core 的最佳起点。

本项目采用了由 Contributor Covenant 定义的规范行为，以明确我们社区中预期的行为。有关更多信息，请参阅 .NET Foundation 行为准则。

General .NET OSS 讨论请见： .NET Foundation Discord

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权利并且确实已经授予我们使用您贡献的权利。有关详细信息，请访问 https://cla.dotnetfoundation.org。

当您提交拉取请求时，CLA-bot 将自动确定您是否需要提供 CLA，并以适当的方式装饰 PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的 CLA 的所有仓库中这样做一次。

许可证

Docker.DotNet licensed under the MIT license.

版权 (c) .NET Foundation 和贡献者