Meziantou.FrameworkContainerDefinition Class
Describes how a container should be created. Configure an instance and call ContainerDefinition.CreateContainer to obtain a runnable TemporaryContainer.
public class ContainerDefinitionExample
var definition = new ContainerDefinition(ImageSource.FromRegistry("redis:8"));
definition.Environment.Add("TZ", "UTC");
definition.Ports.Add(new ContainerPort(6379));
definition.WaitStrategies.Add(Wait.ForPort(6379));
await using var container = definition.CreateContainer();
await container.StartAsync();Constructors
| Name | Description |
|---|---|
| ContainerDefinition(ContainerDefinition) | Initializes a new instance of the ContainerDefinition class by deep-copying another definition. The copy can be changed even when other belongs to a container. |
| ContainerDefinition(ImageSource) | Initializes a new instance of the ContainerDefinition class. |
ContainerDefinition overloads
ContainerDefinition(ContainerDefinition)
ContainerDefinition.csInitializes a new instance of the ContainerDefinition class by deep-copying another definition. The copy can be changed even when other belongs to a container.
public ContainerDefinition(ContainerDefinition other)Parameters
otherContainerDefinition- The definition to copy.
ContainerDefinition(ImageSource)
ContainerDefinition.csInitializes a new instance of the ContainerDefinition class.
public ContainerDefinition(ImageSource image)Parameters
imageImageSource- The image the container is created from.
Properties
| Name | Description |
|---|---|
| AdditionalCreateArguments | Gets the arguments added to the create command of the CLI runtimes (docker, podman, Apple's container, wslc), right before the image. Use it for an option the definition does not have. |
| CapAdd | Gets the Linux capabilities added to the container, such as NET_ADMIN. |
| CapDrop | Gets the Linux capabilities dropped from the container, such as ALL. |
| Command | Gets the command tokens passed to the container. |
| DockerApiCreateRequestCustomizer | Gets or sets a callback that changes the JSON body of the POST /containers/create request the Docker Engine API runtime sends, right before it is sent. Use it for an option the definition does not have. |
| Entrypoint | Gets the entrypoint override tokens. |
| Environment | Gets the environment variables. |
| ExposedPorts | Gets the ports the container exposes without publishing them to the host. See ContainerDefinition.Ports for the published ports. |
| ExtraHosts | Gets the entries added to the /etc/hosts file of the container. Use ContainerExtraHost.ForHostGateway to reach the host from the container on Linux. |
| Healthcheck | Gets or sets the healthcheck that replaces the one the image declares. null keeps the healthcheck of the image; ContainerHealthcheck.Disabled disables it. |
| Hostname | Gets or sets the container hostname. |
| Image | Gets or sets the image the container is created from. |
| IsReadOnly | Gets a value indicating whether the definition belongs to a container, in which case it can no longer be changed. |
| Labels | Gets the labels. |
| Logging | Gets the logging options. |
| Mounts | Gets the mounts. |
| Name | Gets or sets the container name. When null, the container is named after ContainerDefinition.ReuseId when it is set, and gets a random name otherwise. |
| Network | Gets the network options. |
| Platform | Gets or sets the platform of the image, such as linux/amd64 or linux/arm64. It selects the variant of a multi-platform image that is pulled and run, and the platform a Dockerfile is built for. When null, the runtime picks the platform of the machine. |
| Ports | Gets the published ports. |
| Privileged | Gets or sets a value indicating whether the container runs in privileged mode, with every capability and access to the devices of the host. |
| PullPolicy | Gets or sets the image pull policy. |
| Resources | Gets the resource limits. |
| ReuseId | Gets or sets an identifier used to reuse an existing container across runs. When set, the container is not removed on dispose. |
| Runtime | Gets or sets the container runtime to use. |
| StartupTimeout | Gets or sets the maximum time TemporaryContainer.WaitUntilReadyAsync waits for all wait strategies to complete. |
| StopSignal | Gets or sets the signal sent to the container to stop it, such as SIGINT. null keeps the one of the image, or SIGTERM. |
| StopTimeout | Gets or sets the time the runtime waits for the container to stop before killing it. null keeps the default of the runtime (10 seconds for docker). The value is rounded down to whole seconds. |
| User | Gets or sets the user the container runs as. |
| WaitStrategies | Gets the wait strategies run when the container starts. |
| WorkingDirectory | Gets or sets the working directory inside the container. |
AdditionalCreateArguments
ContainerDefinition.csGets the arguments added to the create command of the CLI runtimes (docker, podman, Apple's container, wslc), right before the image. Use it for an option the definition does not have.
Property value
Remarks
The Docker Engine API runtime ignores these arguments; use ContainerDefinition.DockerApiCreateRequestCustomizer instead. The library does not check them: an argument the runtime does not know makes the creation fail.
CapAdd
ContainerDefinition.csGets the Linux capabilities added to the container, such as NET_ADMIN.
Property value
CapDrop
ContainerDefinition.csGets the Linux capabilities dropped from the container, such as ALL.
Property value
Command
ContainerDefinition.csGets the command tokens passed to the container.
public ContainerCommandCollection Command { get; }Property value
DockerApiCreateRequestCustomizer
ContainerDefinition.csGets or sets a callback that changes the JSON body of the POST /containers/create request the Docker Engine API runtime sends, right before it is sent. Use it for an option the definition does not have.
public Action<JsonObject>? DockerApiCreateRequestCustomizer { get; set; }Property value
Remarks
The CLI runtimes ignore the callback; use ContainerDefinition.AdditionalCreateArguments instead.
The callback is not part of the configuration a container reused through ContainerDefinition.ReuseId is matched against, since what it does cannot be compared: change the ContainerDefinition.ReuseId when you change what it does.
Entrypoint
ContainerDefinition.csGets the entrypoint override tokens.
public ContainerCommandCollection Entrypoint { get; }Property value
Environment
ContainerDefinition.csGets the environment variables.
public ContainerEnvironmentCollection Environment { get; }Property value
ExposedPorts
ContainerDefinition.csGets the ports the container exposes without publishing them to the host. See ContainerDefinition.Ports for the published ports.
public IList<ContainerExposedPort> ExposedPorts { get; }Property value
Remarks
Apple's container runtime does not support exposing a port.
ExtraHosts
ContainerDefinition.csGets the entries added to the /etc/hosts file of the container. Use ContainerExtraHost.ForHostGateway to reach the host from the container on Linux.
public IList<ContainerExtraHost> ExtraHosts { get; }Property value
Remarks
Apple's container runtime does not support extra hosts.
Healthcheck
ContainerDefinition.csGets or sets the healthcheck that replaces the one the image declares. null keeps the healthcheck of the image; ContainerHealthcheck.Disabled disables it.
public ContainerHealthcheck? Healthcheck { get; set; }Hostname
ContainerDefinition.csGets or sets the image the container is created from.
public ImageSource Image { get; set; }Property value
IsReadOnly
ContainerDefinition.csLabels
ContainerDefinition.csLogging
ContainerDefinition.csMounts
ContainerDefinition.csGets or sets the container name. When null, the container is named after ContainerDefinition.ReuseId when it is set, and gets a random name otherwise.
public string? Name { get; set; }Property value
Network
ContainerDefinition.csPlatform
ContainerDefinition.csGets or sets the platform of the image, such as linux/amd64 or linux/arm64. It selects the variant of a multi-platform image that is pulled and run, and the platform a Dockerfile is built for. When null, the runtime picks the platform of the machine.
public string? Platform { get; set; }Property value
Remarks
Running an image of another architecture requires emulation, such as Rosetta on Apple Silicon or QEMU on Linux.
Privileged
ContainerDefinition.csPullPolicy
ContainerDefinition.csResources
ContainerDefinition.csReuseId
ContainerDefinition.csGets or sets an identifier used to reuse an existing container across runs. When set, the container is not removed on dispose.
public string? ReuseId { get; set; }Property value
Remarks
A container is only adopted when it was created from the same definition. The credentials generated by the database helpers are the exception: every process generates its own, so the ones the container was created with are read back from it.
Runtime
ContainerDefinition.csGets or sets the container runtime to use.
public ContainerRuntime Runtime { get; set; }Property value
StartupTimeout
ContainerDefinition.csGets or sets the maximum time TemporaryContainer.WaitUntilReadyAsync waits for all wait strategies to complete.
public TimeSpan StartupTimeout { get; set; }Property value
StopSignal
ContainerDefinition.csStopTimeout
ContainerDefinition.csGets or sets the time the runtime waits for the container to stop before killing it. null keeps the default of the runtime (10 seconds for docker). The value is rounded down to whole seconds.
public TimeSpan? StopTimeout { get; set; }WaitStrategies
ContainerDefinition.csGets the wait strategies run when the container starts.
public ContainerWaitStrategyCollection WaitStrategies { get; }Property value
WorkingDirectory
ContainerDefinition.csMethods
| Name | Description |
|---|---|
| CreateContainer() | Creates a TemporaryContainer from a deep copy of this definition. Later changes to this definition do not affect the returned container, and the copy the container owns cannot be changed. |
CreateContainer()
ContainerDefinition.csCreates a TemporaryContainer from a deep copy of this definition. Later changes to this definition do not affect the returned container, and the copy the container owns cannot be changed.
public virtual TemporaryContainer CreateContainer()Returns
TemporaryContainer A new container.