Add support for copying existing files via WithContainerFiles API

[danegsta]

Description

Adds the ability to specify an existing file via WithContainerFiles instead of having to specify the contents of a file. Uses the same permission mechanics and slots into the existing ability to create arbitrary files and folders. Specifically, a ContainerFile type passed to WithContainerFiles can take either a Contents property or SourcePath property (an exception will be thrown if both are set).

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire-docs issue (consider using one of the following templates):
      • New (or update) doc-idea template
      • New breaking-change template
      • New diagnostic template
  • No

[Copilot]

Pull Request Overview

This PR adds support for copying existing files via the WithContainerFiles API, replacing the previous bind mount mechanism for realm imports in Keycloak.

• Updated tests to validate the new ContainerFileSystemCallbackAnnotation functionality via asynchronous execution.
• Modified the Container model to enforce that file entries use either SourcePath or Contents but not both.
• Updated the KeycloakResourceBuilderExtensions to utilize the WithContainerFiles API using new C# 12 collection patterns.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
tests/Aspire.Hosting.Keycloak.Tests/KeycloakPublicApiTests.cs	Updated test methods to async, altered assertions to verify ContainerFileSystemCallbackAnnotation usage.
src/Aspire.Hosting/Dcp/Model/Container.cs	Added Source assignment from SourcePath and mutual exclusion check between Contents and SourcePath.
src/Aspire.Hosting/ApplicationModel/ContainerFileSystemCallbackAnnotation.cs	Updated documentation for ContainerFile to clarify mutual exclusion semantics between Contents and SourcePath.
src/Aspire.Hosting/Keycloak/KeycloakResourceBuilderExtensions.cs	Switched from WithBindMount to WithContainerFiles using new collection initialization syntax.

Comments suppressed due to low confidence (1)

tests/Aspire.Hosting.Keycloak.Tests/KeycloakPublicApiTests.cs:224

• The variable 'file' is used in the assertion but is not defined anywhere in the test. Consider defining it (e.g., var file = Path.GetFileName(filePath);) before using it in assertions.

Assert.Equal(file, realmFile.Name);

[karolz-ms]

No bind mount 😍

[eerhardt]

Why does the path need to be absolute? We can use relative paths elsewhere.

[danegsta]

We don’t explicitly check for an absolute path; it’s more of a SHOULD requirement. We can’t necessarily guarantee the orchestrator and container runtime will have the correct working directory in all scenarios, so absolute paths guarantees consistent behavior. We probably should call out the same for the bind mount annotation.

[eerhardt]

Are there any direct tests that can be added for this functionality? If we ever deleted Keycloak (unlikely) we wouldn't have any coverage.