Meziantou.FrameworkTemporaryContainer Class
A temporary container created from a ContainerDefinition. Dispose the instance to remove the container (unless ContainerDefinition.ReuseId is set).
public class TemporaryContainer : IAsyncDisposable- Implements
Properties
| Name | Description |
|---|---|
| Definition | Gets the definition owned by this container. It is read-only: the container reads it at every step of its life. |
| Id | Gets the container id. |
| Name | Gets the container name. |
| Runtime | Gets the container runtime in use. |
Definition
TemporaryContainer.csGets the definition owned by this container. It is read-only: the container reads it at every step of its life.
public ContainerDefinition Definition { get; }Property value
Gets the container id.
public string Id { get; }Gets the container name.
public string Name { get; }Runtime
TemporaryContainer.csMethods
| Name | Description |
|---|---|
| CopyFromContainerAsync(string, string, CancellationToken) | Copies a file or directory from the container to the host. |
| CopyToContainerAsync(string, string, CancellationToken) | Copies a file or directory from the host into the container. |
| DeleteAsync(CancellationToken) | Removes the container, and the image built for it. A later TemporaryContainer.StartAsync or TemporaryContainer.EnsureCreatedAsync creates a new container. |
| DisposeAsync() | Removes the container, and the image built for it, unless ContainerDefinition.ReuseId is set. Cleanup is best-effort, bounded in time, and never throws. |
| EnsureCreatedAsync(CancellationToken) | Creates the container if it does not exist yet, without starting it. When ContainerDefinition.ReuseId is set, an existing matching container is adopted instead. |
| ExecAsync(Action<ExecOptions>, CancellationToken) | Executes a command inside the running container. |
| ExistsAsync(CancellationToken) | Determines whether the container still exists. |
| GetHostAddress(int) | Gets the host address at which the specified published container port is reached from this machine. |
| GetLogsAsync(ContainerLogsOptions, CancellationToken) | Streams the container logs selected by options. |
| GetLogsAsync(CancellationToken) | Streams the container logs, from the creation of the container, following new lines until the container stops or the enumeration is cancelled. |
| GetMappedPort(int) | Gets the host port mapped to the specified container port. |
| InspectAsync(CancellationToken) | Inspects the container and returns a snapshot of its current state. |
| KillAsync(CancellationToken) | Sends a kill signal to the container. |
| OpenReadAsync(string, CancellationToken) | Reads a file from the container. |
| PauseAsync(CancellationToken) | Pauses the container. |
| RestartAsync(CancellationToken) | Restarts the container and refreshes the published-port mapping. |
| StartAsync(CancellationToken) | Creates the container if needed, starts it, refreshes the published-port mapping, and runs the registered wait strategies. |
| StopAsync(CancellationToken) | Stops the container. |
| UnpauseAsync(CancellationToken) | Resumes a paused container. |
| WaitUntilReadyAsync(CancellationToken) | Runs the registered wait strategies, bounded by ContainerDefinition.StartupTimeout. |
| WriteFileAsync(string, Stream, CancellationToken) | Writes a file to the container, creating or overwriting it. |
CopyFromContainerAsync(string, string, CancellationToken)
TemporaryContainer.Files.csCopies a file or directory from the container to the host.
net10.0
public Task CopyFromContainerAsync(string source, string destination, CancellationToken cancellationToken = default)net11.0
public Task CopyFromContainerAsync(string source, string destination, CancellationToken cancellationToken = default)Parameters
sourcestring- The source path inside the container.
destinationstring- The destination path on the host.
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the copy finishes.
CopyToContainerAsync(string, string, CancellationToken)
TemporaryContainer.Files.csCopies a file or directory from the host into the container.
net10.0
public Task CopyToContainerAsync(string source, string destination, CancellationToken cancellationToken = default)net11.0
public Task CopyToContainerAsync(string source, string destination, CancellationToken cancellationToken = default)Parameters
sourcestring- The source path on the host.
destinationstring- The destination path inside the container.
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the copy finishes.
DeleteAsync(CancellationToken)
TemporaryContainer.Lifecycle.csRemoves the container, and the image built for it. A later TemporaryContainer.StartAsync or TemporaryContainer.EnsureCreatedAsync creates a new container.
net10.0
public Task DeleteAsync(CancellationToken cancellationToken = default)net11.0
public Task DeleteAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container is removed.
DisposeAsync()
TemporaryContainer.csRemoves the container, and the image built for it, unless ContainerDefinition.ReuseId is set. Cleanup is best-effort, bounded in time, and never throws.
net10.0
public ValueTask DisposeAsync()net11.0
public ValueTask DisposeAsync()Returns
ValueTask A task that completes once cleanup finishes.
EnsureCreatedAsync(CancellationToken)
TemporaryContainer.csCreates the container if it does not exist yet, without starting it. When ContainerDefinition.ReuseId is set, an existing matching container is adopted instead.
net10.0
public Task EnsureCreatedAsync(CancellationToken cancellationToken = default)net11.0
public Task EnsureCreatedAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container exists.
Exceptions
InvalidOperationException- The container found through
ContainerDefinition.ReuseIdwas created from a different definition.
ExecAsync(Action<ExecOptions>, CancellationToken)
TemporaryContainer.Exec.csExecutes a command inside the running container.
net10.0
public Task<ExecResult> ExecAsync(Action<ExecOptions> configure, CancellationToken cancellationToken = default)net11.0
public Task<ExecResult> ExecAsync(Action<ExecOptions> configure, CancellationToken cancellationToken = default)Parameters
configureAction<ExecOptions>- A callback used to configure the command and its options.
cancellationTokenCancellationToken- A cancellation token.
Returns
Task<ExecResult> The exit code and captured output of the command. Call ExecResult.EnsureSuccess to throw when the command failed.
Exceptions
TimeoutException- The command did not exit within
ExecOptions.Timeout.
ExistsAsync(CancellationToken)
TemporaryContainer.Lifecycle.csDetermines whether the container still exists.
net10.0
public Task<bool> ExistsAsync(CancellationToken cancellationToken = default)net11.0
public Task<bool> ExistsAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task<bool> true if the container exists; otherwise, false.
GetHostAddress(int)
TemporaryContainer.csGets the host address at which the specified published container port is reached from this machine.
Parameters
containerPortint- The container port.
Returns
string The host name or IP address to connect to, together with TemporaryContainer.GetMappedPort. An IPv6 address is returned without brackets.
- A port bound to a specific address (
ContainerPort.HostIp) is reached on that address. - A port bound to every interface is reached on the host of a daemon that runs on another machine (a
tcp://orssh://endpoint), and on the loopback address otherwise.
Exceptions
InvalidOperationException- The port mapping is not available (the container has not been started) or the port is not published.
GetLogsAsync overloads
GetLogsAsync(ContainerLogsOptions, CancellationToken)
TemporaryContainer.Logs.csStreams the container logs selected by options.
public IAsyncEnumerable<LogEntry> GetLogsAsync(ContainerLogsOptions options, CancellationToken cancellationToken = default)Parameters
optionsContainerLogsOptions- The entries to return: a time range, the last entries, the streams, and whether to follow the new entries.
cancellationTokenCancellationToken- A cancellation token that stops following the logs.
Returns
IAsyncEnumerable<LogEntry> An asynchronous sequence of log entries.
Exceptions
ArgumentException- Both
ContainerLogsOptions.IncludeStandardOutputandContainerLogsOptions.IncludeStandardErrorarefalse. NotSupportedExceptionContainerLogsOptions.SinceorContainerLogsOptions.Untilis set, and the runtime does not record timestamps.
GetLogsAsync(CancellationToken)
TemporaryContainer.Logs.csStreams the container logs, from the creation of the container, following new lines until the container stops or the enumeration is cancelled.
public IAsyncEnumerable<LogEntry> GetLogsAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token that stops following the logs.
Returns
IAsyncEnumerable<LogEntry> An asynchronous sequence of log entries.
GetMappedPort(int)
TemporaryContainer.csGets the host port mapped to the specified container port.
Parameters
containerPortint- The container port.
Returns
int The host port.
Exceptions
InvalidOperationException- The port mapping is not available (the container has not been started) or the port is not published.
InspectAsync(CancellationToken)
TemporaryContainer.Inspect.csInspects the container and returns a snapshot of its current state.
net10.0
public Task<ContainerInfo> InspectAsync(CancellationToken cancellationToken = default)net11.0
public Task<ContainerInfo> InspectAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task<ContainerInfo> The container information.
KillAsync(CancellationToken)
TemporaryContainer.Lifecycle.csSends a kill signal to the container.
net10.0
public Task KillAsync(CancellationToken cancellationToken = default)net11.0
public Task KillAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container is killed.
OpenReadAsync(string, CancellationToken)
TemporaryContainer.Files.csReads a file from the container.
net10.0
public Task<Stream> OpenReadAsync(string path, CancellationToken cancellationToken = default)net11.0
public Task<Stream> OpenReadAsync(string path, CancellationToken cancellationToken = default)Parameters
pathstring- The path of the file inside the container.
cancellationTokenCancellationToken- A cancellation token.
Returns
Task<Stream> A readable stream positioned at the beginning of the file content. Dispose it once read.
Remarks
The file is not loaded in memory. The Docker Engine API runtime reads it from the daemon as the stream is read, so the stream cannot seek, but its Stream.Length is known; copy it to a MemoryStream when you need to seek. The CLI runtimes copy it to a temporary file first, deleted when the stream is disposed.
PauseAsync(CancellationToken)
TemporaryContainer.Lifecycle.csPauses the container.
net10.0
public Task PauseAsync(CancellationToken cancellationToken = default)net11.0
public Task PauseAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container is paused.
Exceptions
NotSupportedException- The runtime does not support pausing containers.
RestartAsync(CancellationToken)
TemporaryContainer.Lifecycle.csRestarts the container and refreshes the published-port mapping.
net10.0
public Task RestartAsync(CancellationToken cancellationToken = default)net11.0
public Task RestartAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container has restarted.
StartAsync(CancellationToken)
TemporaryContainer.csCreates the container if needed, starts it, refreshes the published-port mapping, and runs the registered wait strategies.
net10.0
public Task StartAsync(CancellationToken cancellationToken = default)net11.0
public Task StartAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container is started and ready.
StopAsync(CancellationToken)
TemporaryContainer.Lifecycle.csStops the container.
net10.0
public Task StopAsync(CancellationToken cancellationToken = default)net11.0
public Task StopAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container has stopped.
UnpauseAsync(CancellationToken)
TemporaryContainer.Lifecycle.csResumes a paused container.
net10.0
public Task UnpauseAsync(CancellationToken cancellationToken = default)net11.0
public Task UnpauseAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the container is resumed.
Exceptions
NotSupportedException- The runtime does not support pausing containers.
WaitUntilReadyAsync(CancellationToken)
TemporaryContainer.csRuns the registered wait strategies, bounded by ContainerDefinition.StartupTimeout.
net10.0
public Task WaitUntilReadyAsync(CancellationToken cancellationToken = default)net11.0
public Task WaitUntilReadyAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once every wait strategy has completed.
Exceptions
TimeoutException- The container was not ready within
ContainerDefinition.StartupTimeout.
WriteFileAsync(string, Stream, CancellationToken)
TemporaryContainer.Files.csWrites a file to the container, creating or overwriting it.
net10.0
public Task WriteFileAsync(string path, Stream content, CancellationToken cancellationToken = default)net11.0
public Task WriteFileAsync(string path, Stream content, CancellationToken cancellationToken = default)Parameters
pathstring- The destination path inside the container.
contentStream- The content to write. It is read from its current position to its end, and is not disposed.
cancellationTokenCancellationToken- A cancellation token.
Returns
Task A task that completes once the file is written.
Remarks
The content is not loaded in memory. The Docker Engine API runtime sends a seekable stream as it reads it, and copies any other stream to a temporary file first, since the archive it sends declares the length of the file before its content.