Provides access to functionality involving Docker containers. More...
Public Member Functions | |
| Task< IContainer > | CreateAndStartAsync (string image, CancellationToken ct=default) |
| Creates a Docker container and starts it. More... | |
| Task< IContainer > | CreateAndStartAsync (ImageReference image, CancellationToken ct=default) |
| Creates a Docker container and starts it. More... | |
| Task< IContainer > | CreateAndStartAsync (string image, CreateContainerOptions options, CancellationToken ct=default) |
| Creates a Docker container and starts it. More... | |
| async Task< IContainer > | CreateAndStartAsync (ImageReference image, CreateContainerOptions options, CancellationToken ct=default) |
| Creates a Docker container and starts it. More... | |
| Task< IContainer > | CreateAsync (string image, CancellationToken ct=default) |
| Creates a Docker container from an image. More... | |
| Task< IContainer > | CreateAsync (ImageReference image, CancellationToken ct=default) |
| Creates a Docker container from an image. More... | |
| Task< IContainer > | CreateAsync (string image, CreateContainerOptions options, CancellationToken ct=default) |
| Creates a Docker container from an image. More... | |
| async Task< IContainer > | CreateAsync (ImageReference image, CreateContainerOptions options, CancellationToken ct=default) |
| Creates a Docker container from an image. More... | |
| Task< IContainer > | GetAsync (string container, CancellationToken ct=default) |
| Loads an object that can be used to interact with the indicated container. More... | |
| async Task< IContainer > | GetAsync (ContainerReference container, CancellationToken ct=default) |
| Loads an object that can be used to interact with the indicated container. More... | |
| Task< IContainerInfo > | GetDetailsAsync (string container, CancellationToken ct=default) |
| Gets detailed information about a container. More... | |
| async Task< IContainerInfo > | GetDetailsAsync (ContainerReference container, CancellationToken ct=default) |
| Gets detailed information about a container. More... | |
| Task< IReadOnlyList< IContainer > > | ListAsync (CancellationToken ct=default) |
| Gets a list of Docker containers known to the daemon. More... | |
| async Task< IReadOnlyList< IContainer > > | ListAsync (ListContainersOptions options, CancellationToken ct=default) |
| Gets a list of Docker containers known to the daemon. More... | |
| Task | StartAsync (string container, CancellationToken ct=default) |
| Starts a Docker container, if it is not already running. More... | |
| async Task | StartAsync (ContainerReference container, CancellationToken ct=default) |
| Starts a Docker container, if it is not already running. More... | |
| IDisposable | Subscribe (IObserver< ContainerEvent > observer) |
| Subscribes to events about containers. More... | |
Detailed Description
Provides access to functionality involving Docker containers.
Not all container functionality is available directly on this class. See Container for more functionality.
Member Function Documentation
◆ CreateAndStartAsync() [1/4]
| Task<IContainer> DockerSdk.Containers.ContainerAccess.CreateAndStartAsync | ( | ImageReference | image, |
| CancellationToken | ct = default |
||
| ) |
Creates a Docker container and starts it.
- Parameters
-
image The image to create the container from. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves when the container's main process has started.
From the perspective of Docker, there's no concept of whether the container's main process has "finished
starting"–just that the process has been started at all. Thus, for example, if the process is a web server, this method's Task may resolve before the web server is ready for connections. If the application using this library needs to synchronize with events happening inside the container, it should monitor the container's logs or use other real-time mechanisms to do so.
It's also possible that a short-lived process might exit before the method's Task resolves.
- Exceptions
-
ArgumentException image is null. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout.
◆ CreateAndStartAsync() [2/4]
|
inline |
Creates a Docker container and starts it.
- Parameters
-
image The image to create the container from. options Options for how to create the image and how it should behave. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves when the container's main process has started.
From the perspective of Docker, there's no concept of whether the container's main process has "finished
starting"–just that the process has been started at all. Thus, for example, if the process is a web server, this method's Task may resolve before the web server is ready for connections. If the application using this library needs to synchronize with events happening inside the container, it should monitor the container's logs or use other real-time mechanisms to do so.
It's also possible that a short-lived process might exit before the method's Task resolves.
- Exceptions
-
ArgumentException image and/or options are null. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. ImageNotFoundRemotelyException The Docker image does not exist, even remotely. (Only applies when pulling an image, which is not enabled by default.) NetworkNotFoundException One of the networks specified does not exist. MalformedReferenceException The options specified a name for the image, but the name does not meet the expectations of a well-formed container name. RegistryAuthException The registry requires credentials that the client hasn't been given. (Only applies when pulling an image, which is not enabled by default.) System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout.
◆ CreateAndStartAsync() [3/4]
| Task<IContainer> DockerSdk.Containers.ContainerAccess.CreateAndStartAsync | ( | string | image, |
| CancellationToken | ct = default |
||
| ) |
Creates a Docker container and starts it.
- Parameters
-
image The image to create the container from. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves when the container's main process has started.
From the perspective of Docker, there's no concept of whether the container's main process has "finished
starting"–just that the process has been started at all. Thus, for example, if the process is a web server, this method's Task may resolve before the web server is ready for connections. If the application using this library needs to synchronize with events happening inside the container, it should monitor the container's logs or use other real-time mechanisms to do so.
It's also possible that a short-lived process might exit before the method's Task resolves.
- Exceptions
-
ArgumentException image is null or empty. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout. MalformedReferenceException The image input is not well-formed.
◆ CreateAndStartAsync() [4/4]
| Task<IContainer> DockerSdk.Containers.ContainerAccess.CreateAndStartAsync | ( | string | image, |
| CreateContainerOptions | options, | ||
| CancellationToken | ct = default |
||
| ) |
Creates a Docker container and starts it.
- Parameters
-
image The image to create the container from. options Options for how to create the image and how it should behave. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves when the container's main process has started.
From the perspective of Docker, there's no concept of whether the container's main process has "finished
starting"–just that the process has been started at all. Thus, for example, if the process is a web server, this method's Task may resolve before the web server is ready for connections. If the application using this library needs to synchronize with events happening inside the container, it should monitor the container's logs or use other real-time mechanisms to do so.
It's also possible that a short-lived process might exit before the method's Task resolves.
- Exceptions
-
ArgumentException image and/or options are null. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. ImageNotFoundRemotelyException The Docker image does not exist, even remotely. (Only applies when pulling an image, which is not enabled by default.) NetworkNotFoundException One of the networks specified does not exist. MalformedReferenceException The image input is not well-formed. –or– The options specified a name for the image, but the name does not meet the expectations of a well-formed container name. RegistryAuthException The registry requires credentials that the client hasn't been given. (Only applies when pulling an image, which is not enabled by default.) System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout.
◆ CreateAsync() [1/4]
| Task<IContainer> DockerSdk.Containers.ContainerAccess.CreateAsync | ( | ImageReference | image, |
| CancellationToken | ct = default |
||
| ) |
Creates a Docker container from an image.
- Parameters
-
image The image to create the container from. ct A token used to cancel the operation.
- Returns
- Exceptions
-
ArgumentException image is null. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout.
◆ CreateAsync() [2/4]
|
inline |
Creates a Docker container from an image.
- Parameters
-
image The image to create the container from. options Options for how to create the image and how it should behave. ct A token used to cancel the operation.
- Returns
- Exceptions
-
ArgumentException image and/or options are null. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. ImageNotFoundRemotelyException The Docker image does not exist, even remotely. (Only applies when pulling an image, which is not enabled by default.) MalformedReferenceException The options specified a name for the image, but the name does not meet the expectations of a well-formed container name. RegistryAuthException The registry requires credentials that the client hasn't been given. (Only applies when pulling an image, which is not enabled by default.) System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout.
◆ CreateAsync() [3/4]
| Task<IContainer> DockerSdk.Containers.ContainerAccess.CreateAsync | ( | string | image, |
| CancellationToken | ct = default |
||
| ) |
Creates a Docker container from an image.
- Parameters
-
image The image to create the container from. ct A token used to cancel the operation.
- Returns
- Exceptions
-
ArgumentException image is null or empty. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout. MalformedReferenceException The image input is not a validly-formatted image reference.
◆ CreateAsync() [4/4]
| Task<IContainer> DockerSdk.Containers.ContainerAccess.CreateAsync | ( | string | image, |
| CreateContainerOptions | options, | ||
| CancellationToken | ct = default |
||
| ) |
Creates a Docker container from an image.
- Parameters
-
image The image to create the container from. options Options for how to create the image and how it should behave. ct A token used to cancel the operation.
- Returns
- Exceptions
-
ArgumentException image and/or options are null or empty. ImageNotFoundLocallyException The Docker daemon cannot find the image locally, and the CreateContainerOptions.PullCondition option is not set to pull it automatically. ImageNotFoundRemotelyException The Docker image does not exist, even remotely. (Only applies when pulling an image, which is not enabled by default.) MalformedReferenceException The image name is not well-formed. –or– The options specified a name for the image, but the name does not meet the expectations of a well-formed container name. RegistryAuthException The registry requires credentials that the client hasn't been given. (Only applies when pulling an image, which is not enabled by default.) System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout.
◆ GetAsync() [1/2]
|
inline |
Loads an object that can be used to interact with the indicated container.
- Parameters
-
container A container name or ID. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves to the container object.
- Exceptions
-
ArgumentException container is null. ContainerNotFoundException No such container exists. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as loss of network connectivity.
Caution: Container names and short IDs are not guaranteed to be unique. If there is more than one match for the reference, the result is undefined.
◆ GetAsync() [2/2]
| Task<IContainer> DockerSdk.Containers.ContainerAccess.GetAsync | ( | string | container, |
| CancellationToken | ct = default |
||
| ) |
Loads an object that can be used to interact with the indicated container.
- Parameters
-
container A container name or ID. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves to the container object.
- Exceptions
-
ContainerNotFoundException No such container exists. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as loss of network connectivity. MalformedReferenceException The container reference is improperly formatted. ArgumentException container is null or empty.
Caution: Container names and short IDs are not guaranteed to be unique. If there is more than one match for the reference, the result is undefined.
◆ GetDetailsAsync() [1/2]
|
inline |
Gets detailed information about a container.
- Parameters
-
container The name or ID of a container. ct A CancellationToken used to cancel the operation.
- Returns
- A Task that completes when the result is available.
- Exceptions
-
ArgumentNullException container is null. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout. ContainerNotFoundException The daemon doesn't know of a container matching the given ID or name.
◆ GetDetailsAsync() [2/2]
| Task<IContainerInfo> DockerSdk.Containers.ContainerAccess.GetDetailsAsync | ( | string | container, |
| CancellationToken | ct = default |
||
| ) |
Gets detailed information about a container.
- Parameters
-
container The name or ID of a container. ct A CancellationToken used to cancel the operation.
- Returns
- A Task that completes when the result is available.
- Exceptions
-
System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout. ContainerNotFoundException The daemon doesn't know of a container matching the given ID or name. MalformedReferenceException The given reference isn't in a valid format for a container ID or name. ArgumentException container is null or empty.
◆ ListAsync() [1/2]
| Task<IReadOnlyList<IContainer> > DockerSdk.Containers.ContainerAccess.ListAsync | ( | CancellationToken | ct = default | ) |
Gets a list of Docker containers known to the daemon.
- Parameters
-
ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves to the list of containers.
This method does not necessarily return the same results as the docker image ls command. To get the same results, use the ListAsync(ListContainersOptions, CancellationToken) overload and give it the ListContainersOptions.CommandLineDefaults options.
The sequence of the results is undefined.
◆ ListAsync() [2/2]
|
inline |
Gets a list of Docker containers known to the daemon.
- Parameters
-
options Filters for the search. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves to the list of containers.
- Exceptions
-
ArgumentNullException options is null.
This method does not necessarily return the same results as the docker image ls command. To get the same results, pass in ListContainersOptions.CommandLineDefaults.
The sequence of the results is undefined.
◆ StartAsync() [1/2]
|
inline |
Starts a Docker container, if it is not already running.
- Parameters
-
container The container to start. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves when the container's main process has started.
From the perspective of Docker, there's no concept of whether the container's main process has "finished
starting"–just that the process has been started at all. Thus, for example, if the process is a web server, this method's Task may resolve before the web server is ready for connections. If the application using this library needs to synchronize with events happening inside the container, it should monitor the container's logs or use other real-time mechanisms to do so.
It's also possible that a short-lived process might exit before the method's Task resolves.
- Exceptions
-
ArgumentException container is null. ContainerNotFoundException The indicated container does not exist. NetworkNotFoundException One of the networks specified during container creation does not exist. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout.
◆ StartAsync() [2/2]
| Task DockerSdk.Containers.ContainerAccess.StartAsync | ( | string | container, |
| CancellationToken | ct = default |
||
| ) |
Starts a Docker container, if it is not already running.
- Parameters
-
container The container to start. ct A token used to cancel the operation.
- Returns
- A Task<TResult> that resolves when the container's main process has started.
From the perspective of Docker, there's no concept of whether the container's main process has "finished
starting"–just that the process has been started at all. Thus, for example, if the process is a web server, this method's Task may resolve before the web server is ready for connections. If the application using this library needs to synchronize with events happening inside the container, it should monitor the container's logs or use other real-time mechanisms to do so.
It's also possible that a short-lived process might exit before the method's Task resolves.
- Exceptions
-
ContainerNotFoundException The indicated container does not exist. NetworkNotFoundException One of the networks specified during container creation does not exist. System.Net.Http.HttpRequestException The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation, or timeout. MalformedReferenceException The container input is not a well-formed container reference. ArgumentException container is null or empty.
◆ Subscribe()
| IDisposable DockerSdk.Containers.ContainerAccess.Subscribe | ( | IObserver< ContainerEvent > | observer | ) |
Subscribes to events about containers.
- Parameters
-
observer An object to observe the events.
- Returns
- An IDisposable representing the subscription. Disposing this unsubscribes and releases resources.
The documentation for this class was generated from the following file:
- Containers/ContainerAccess.cs
