fix: Add Platform type

Author: HofmeisterAn

docs/api/create_docker_container.md

@@ -4,7 +4,7 @@ Testcontainers' generic container support offers the greatest flexibility and ma
 
 ## Configure container image
 
-Use `WithImage(...)` to specify the container image.
+To specify the container image, use `WithImage(...)`.
 
 The simplest overload accepts a `string`:
 
@@ -13,13 +13,19 @@ _ = new ContainerBuilder()
   .WithImage("postgres:15.1");
 ```
 
-For platform-specific scenarios, `WithImage` also accepts an `IImage`. Using the `DockerImage` implementation, you can explicitly set the platform:
+For more advanced scenarios, `WithImage` also supports `IImage`, giving you more control over how the image is represented and its properties are resolved.
+
+If you need to target a specific platform, the `DockerImage` implementation provides an overload that lets you explicitly set the platform, such as `linux/amd64`.
 
 ```csharp
 _ = new ContainerBuilder()
-  .WithImage(new DockerImage("postgres:15.1", "linux/amd64"));
+  .WithImage(new DockerImage("postgres:15.1", new Platform("linux/amd64")));
 ```
 
+!!!tip
+
+    A specifier has the format `<os>|<arch>|<os>/<arch>[/<variant>]`. The user can provide either the operating system or the architecture or both. For more details, [see containerd/platforms](https://github.com/containerd/platforms).
+
 ## Configure container start
 
 Both `ENTRYPOINT` and `CMD` allows you to configure an executable and parameters, that a container runs at the start. By default, a container will run whatever `ENTRYPOINT` or `CMD` is specified in the Docker container image. At least one of both configurations is necessary. The container builder implementation supports `WithEntrypoint(params string[])` and `WithCommand(params string[])` to set or override the executable. Ideally, the `ENTRYPOINT` should set the container's executable, whereas the `CMD` sets the default arguments for the `ENTRYPOINT`.

src/Testcontainers/Clients/DockerContainerOperations.cs

@@ -202,6 +202,7 @@ public async Task<string> RunAsync(IContainerConfiguration configuration, Cancel
       var createParameters = new CreateContainerParameters
       {
         Image = configuration.Image.FullName,
+        Platform = configuration.Image.Platform,
         Name = configuration.Name,
         Hostname = configuration.Hostname,
         WorkingDir = configuration.WorkingDirectory,

src/Testcontainers/Images/DockerImage.cs

@@ -56,20 +56,15 @@ public DockerImage(string image)
     /// <summary>
     /// Initializes a new instance of the <see cref="DockerImage" /> class.
     /// </summary>
-    /// <remarks>
-    /// The supported format for <paramref name="platform" /> is <c>&lt;os&gt;|&lt;arch&gt;|&lt;os&gt;/&lt;arch&gt;[/&lt;variant&gt;]</c>.
-    /// You can provide the operating system, the architecture, or both.
-    /// For more details and examples, see <see href="https://github.com/containerd/platforms">containerd/platforms</see>.
-    /// </remarks>
     /// <param name="image">The image.</param>
     /// <param name="platform">The platform.</param>
     /// <example><c>fedora/httpd:version1.0</c> where <c>fedora/httpd</c> is the repository and <c>version1.0</c> the tag.</example>
     public DockerImage(
       string image,
-      string platform)
+      Platform platform)
       : this(GetDockerImage(image))
     {
-      _platform = TrimOrDefault(platform);
+      _platform = platform.Value;
     }
 
     /// <summary>

src/Testcontainers/Images/DockerfileArchive.cs

@@ -170,7 +170,7 @@ public IEnumerable<IImage> GetBaseImages()
         {
           var fromArgs = ParseFromArgs(item.Arg).ToDictionary(arg => arg.Name, arg => arg.Value);
           _ = fromArgs.TryGetValue("platform", out var platform);
-          return new DockerImage(item.Image, platform);
+          return new DockerImage(item.Image, new Platform(platform));
         })
         .ToArray();
 
@@ -339,11 +339,8 @@ private static string ReplaceVariables(string line, IDictionary<string, string>
     /// quotes (<c>'</c>) are supported. Whitespaces outside of quotes are
     /// treated as separators.
     ///
-    /// For example, the line:
-    /// <code>
-    ///   --pull=always --platform="linux/amd64"
-    /// </code>
-    /// becomes:
+    /// E.g., the line <c>--pull=always --platform="linux/amd64"</c> becomes:
+    ///
     /// <list type="bullet">
     ///   <item>
     ///     <description>
@@ -393,7 +390,7 @@ private static string ReplaceVariables(string line, IDictionary<string, string>
 
         if (i > start)
         {
-          yield return ParseFlag(line.Substring(start, i - start));
+          yield return ParseArg(line.Substring(start, i - start));
         }
 
         start = i + 1;
@@ -406,18 +403,18 @@ private static string ReplaceVariables(string line, IDictionary<string, string>
 
       if (line.Length > start)
       {
-        yield return ParseFlag(line.Substring(start));
+        yield return ParseArg(line.Substring(start));
       }
     }
 
     /// <summary>
-    /// Splits a single flag token into a flag name and an optional value.
+    /// Splits a single arg into flag name and an optional value.
     /// </summary>
-    /// <param name="flag">A single flag token, optionally containing an equals sign and value.</param>
+    /// <param name="arg">A single arg, optionally containing an equals sign and value.</param>
     /// <returns>A tuple containing the flag name and its value, or <c>null</c> if no value is specified.</returns>
-    private static (string Name, string Value) ParseFlag(string flag)
+    private static (string Name, string Value) ParseArg(string arg)
     {
-      var trimmed = flag.TrimStart('-');
+      var trimmed = arg.TrimStart('-');
       var eqIndex = trimmed.IndexOf('=');
       if (eqIndex == -1)
       {

src/Testcontainers/Images/IImage.cs

@@ -37,9 +37,8 @@ public interface IImage
     /// Gets the platform.
     /// </summary>
     /// <remarks>
-    /// The supported format is <c>&lt;os&gt;|&lt;arch&gt;|&lt;os&gt;/&lt;arch&gt;[/&lt;variant&gt;]</c>.
-    /// You can provide the operating system, the architecture, or both.
-    /// For more details and examples, see <see href="https://github.com/containerd/platforms">containerd/platforms</see>.
+    /// The supported format for a platform value is:
+    /// <c>&lt;os&gt;|&lt;arch&gt;|&lt;os&gt;/&lt;arch&gt;[/&lt;variant&gt;]</c>.
     /// </remarks>
     [CanBeNull]
     string Platform { get; }

src/Testcontainers/Images/Platform.cs

@@ -0,0 +1,38 @@
+namespace DotNet.Testcontainers.Images
+{
+  using JetBrains.Annotations;
+
+  /// <summary>
+  /// Represents a container platform identifier.
+  /// </summary>
+  /// <remarks>
+  /// The supported format for a platform value is:
+  /// <c>&lt;os&gt;|&lt;arch&gt;|&lt;os&gt;/&lt;arch&gt;[/&lt;variant&gt;]</c>.
+  ///
+  /// You can provide either the operating system or the architecture or both.
+  /// For more details, see <see href="https://github.com/containerd/platforms">containerd/platforms</see>.
+  /// </remarks>
+  [PublicAPI]
+  public readonly struct Platform
+  {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Platform" /> struct.
+    /// </summary>
+    /// <param name="value">The platform identifier.</param>
+    [PublicAPI]
+    public Platform(string value)
+    {
+    }
+
+    /// <summary>
+    /// Gets the platform identifier.
+    /// </summary>
+    /// <remarks>
+    /// A string representing the container platform in <c>containerd/platforms</c> format, or
+    /// <c>null</c> if no platform was specified.
+    /// </remarks>
+    [PublicAPI]
+    [CanBeNull]
+    public string Value { get; }
+  }
+}

tests/Testcontainers.Tests/Unit/Images/ImageFromDockerfileTest.cs

@@ -27,10 +27,10 @@ public void DockerfileArchiveGetBaseImages()
         new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-jammy"),
         new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-noble"),
         new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-alpine"),
-        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", "linux/amd64"),
-        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", "linux/arm64"),
-        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", "linux/arm/v6"),
-        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", "linux/arm/v7"),
+        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", new Platform("linux/amd64")),
+        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", new Platform("linux/arm64")),
+        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", new Platform("linux/arm/v6")),
+        new DockerImage("mcr.microsoft.com/dotnet/aspnet:8.0-azurelinux3.0", new Platform("linux/arm/v7")),
         new DockerImage("mcr.microsoft.com/dotnet/sdk:8.0.414"),
       };