feat: Add image name substitution hook

[HofmeisterAn]

What does this PR do?

Adds TestcontainersSettings.ImageNameSubstitution, a Func<IImage, IImage> hook that lets users replace any image name before it is pulled. This is the .NET equivalent of Java's ImageNameSubstitutor.

The substitution runs before the existing HubImageNamePrefix is applied, so both mechanisms can be combined. Returning null from the function falls back to the original image name.

TestcontainersSettings.ImageNameSubstitution = image => new DockerImage("registry.mycompany.com/mirror/" + image.FullName);

/cc @scrocquesel-ml150

Why is it important?

This helps users to redirect image pulls to a private registry mirror (e.g., to avoid Docker Hub rate limits), apply custom routing rules that go beyond simple prefix matching, and audit or restrict which container images can be used in a build.

Related issues

• Closes [Enhancement]: Add support for image name substitution for all registry (not only DockerHub) #1705

Summary by CodeRabbit

• New Features

  • Added support for custom image name substitution, enabling transformation of container images before deployment.

• Documentation

  • Added documentation for the new image name substitution configuration option.

[netlify]

✅ Deploy Preview for testcontainers-dotnet ready!

Name	Link
🔨 Latest commit	9708ad3
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-dotnet/deploys/6a341f6d70e56400089d932f
😎 Deploy Preview	https://deploy-preview-1710--testcontainers-dotnet.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: dd4146fc-b2fb-42f8-87d1-687f810390f7

📥 Commits

Reviewing files that changed from the base of the PR and between 8394aab and 9708ad3.

📒 Files selected for processing (6)

• docs/custom_configuration/index.md
• src/Testcontainers/Builders/ContainerBuilder3.cs`
• src/Testcontainers/Builders/ImageFromDockerfileBuilder.cs
• src/Testcontainers/Configurations/TestcontainersSettings.cs
• src/Testcontainers/Images/IImageExtensions.cs
• tests/Testcontainers.Tests/Unit/Configurations/DockerImageNameSubstitutionTest.cs

---

Walkthrough

A new ImageNameSubstitution property (Func<IImage, IImage>) is added to TestcontainersSettings. A corresponding ApplyImageNameSubstitution extension method is introduced in IImageExtensions, which applies the substitution (if configured) and then delegates to ApplyHubImageNamePrefix. Both ContainerBuilder and ImageFromDockerfileBuilder are updated to call this new method. Tests gain a shared ImageNameSubstitutionTest base class that resets both settings. Documentation for the new substitution API is added.

Changes

Image Name Substitution

Layer / File(s)	Summary
Settings property and extension method src/Testcontainers/Configurations/TestcontainersSettings.cs, src/Testcontainers/Images/IImageExtensions.cs	ImageNameSubstitution (Func<IImage, IImage>, nullable) is added to TestcontainersSettings. ApplyImageNameSubstitution extension applies the configured function (falling back to the original on null), then calls ApplyHubImageNamePrefix, making substitution run before the hub prefix.
Builder wiring src/Testcontainers/Builders/ContainerBuilder\3.cs, src/Testcontainers/Builders/ImageFromDockerfileBuilder.cs`	WithImage(IImage) and WithName(IImage) swap ApplyHubImageNamePrefix for ApplyImageNameSubstitution, routing all image assignments through the full substitution pipeline.
Tests and documentation tests/Testcontainers.Tests/Unit/Configurations/DockerImageNameSubstitutionTest.cs, docs/custom_configuration/index.md	Abstract ImageNameSubstitutionTest base class resets both HubImageNamePrefix and ImageNameSubstitution on construction and disposal; existing test classes inherit from it. Docs add a "Substitute image names" section with a [ModuleInitializer] example and precedence notes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop, hop, a new trick I've found,
Any registry image can be swapped around!
ImageNameSubstitution sets the stage,
No more DockerHub-only rage.
Return null to keep it the same,
Or swap the image — what a game! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Add image name substitution hook' clearly and concisely summarizes the main feature addition in the changeset.
Description check	✅ Passed	The description includes clear explanations of what the PR does (the WHAT) and why it's important (the WHY), along with a related issue reference (Closes #1705).
Linked Issues check	✅ Passed	The PR fully implements the ImageNameSubstitution feature as described in issue #1705, providing a Func-based hook equivalent to Java's ImageNameSubstitutor that works across all registries.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the image name substitution feature specified in issue #1705; no unrelated modifications are present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/image-name-substitution

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}