Shirubasoft.Aspire.ModularAppHosts 6.0.0

Shirubasoft.Aspire.ModularAppHosts

Define an Aspire resource graph once and reuse it across AppHosts. A module can be added from the current application, imported from a managed Git checkout, and exposed through a generated strongly typed API. Every consumer references the producer-owned C# contract package, while the configured repository supplies the source and build context used to materialize that contract.

Packages

Install the core package in AppHosts and shared module contracts:

dotnet add package Shirubasoft.Aspire.ModularAppHosts

The optional testing package carries Aspire.Hosting.Testing and Docker hosting dependencies. Add it to both the AppHost that declares the test deployment environment and the test project that creates the deployment builder.

dotnet add package Shirubasoft.Aspire.ModularAppHosts.Testing

The runtime packages and tool target .NET 10, the source generator supports .NET SDK 10.0.100 or later, and the Aspire-facing packages require Aspire 13.4.6 or later. Their APIs use the Aspire.Hosting.ModularAppHosts namespace. They are licensed under the MIT License.

Quick start

Prerequisites are .NET SDK 10.0.100 or later, Aspire CLI 13.4 or later, and a running Docker 28+ or Podman 5+ container runtime. In an existing AppHost or shared contract project, install the core package, install the item template, and scaffold a contract:

dotnet add package Shirubasoft.Aspire.ModularAppHosts
dotnet new install Shirubasoft.Aspire.ModularAppHosts.Templates
dotnet new aspire-module --name CatalogModule --moduleName catalog --namespace Catalog.Modules

Replace the generated CatalogModule.cs content with this runnable contract. The generator creates typed properties for its resources:

using Aspire.Hosting;
using Aspire.Hosting.ModularAppHosts;

namespace Catalog.Modules;

[GenerateDistributedApplicationModule(Name, Version = "1", PackageId = "Catalog.Modules")]
public static partial class CatalogModule
{
    public const string Name = "catalog";
    public const string ApiResourceName = "catalog-api";

    public static void Define(IDistributedApplicationModuleBuilder module)
    {
        module.AddContainer(ApiResourceName, "nginx", "alpine")
            .Configure((_, container) =>
                container.WithHttpEndpoint(targetPort: 80, name: "http"));
    }
}

Add the module and use its generated resources like ordinary Aspire resource builders:

var builder = DistributedApplication.CreateBuilder(args);

var catalog = await builder.AddCatalogModuleAsync();

builder.AddContainer("storefront", "nginx", "alpine")
    .WithReference(catalog.Api.GetEndpoint("http"))
    .WaitFor(catalog.Api);

await builder.Build().RunAsync();

From the AppHost directory, run aspire run, open the dashboard URL printed by Aspire, and use the catalog-api endpoint to verify the module is running.

For a repository-backed module, supply its repository through configuration or WithRepository(...) and materialize it with await builder.ImportCatalogModuleAsync(). Packaged contracts can declare specialized projects with ModuleProjectPathBase.Repository, preserving local project debugging without coupling the contract to the consumer's source-tree layout. Import options can prefix or alias resources when a receiving AppHost already uses the contract names. The module guide covers repository-aware factories, project/container selection, identity, and image publishing.

Inside another module's Define method, CatalogModule.Reference(module) returns the same strongly typed API and validates the required contract version. Module definitions can read the AppHost's IConfiguration, use their conventional ConfigurationSection, or call GetOptions<T>() to bind IOptions<T> from Aspire:ModularAppHosts:Modules:<module-name>.

By default, local modules run as projects, imported modules run as containers, and clean imported repositories with a configured upstream are fast-forwarded before startup. Local branches keep their current commit when they lack an upstream or contain changes. Image build commands are opt-in. Set UpdateImportedRepositories or a module's UpdateRepository to false to keep a checkout fixed, and use UseLocalModuleProjects(), UseModuleContainers(), or BuildModuleImages() for AppHost-wide intent.

Module image build commands can follow Aspire's Docker or Podman selection by awaiting ContainerRuntimeResolver.ResolveAsync(). It reads ASPIRE_CONTAINER_RUNTIME, accepts DOTNET_ASPIRE_CONTAINER_RUNTIME, and otherwise probes both runtimes in parallel to prefer one that is running. In publish mode, image publishers contribute build-<resource> steps and registry-backed images participate in aspire do push and aspire do pull; push depends on build, so CI can delegate module-owned build commands to Aspire. Pass declared or effective resource names after any aggregate step to operate on that subset, for example aspire do pull catalog-api catalog-worker. aspire do describe-images --output-path artifacts writes the same effective run, pull, push, and build identities to artifacts/module-images.json for CI tooling. A resource-level WithImagePullMapping can pull a remote reference from one registry and re-tag it as the resource image in another registry while retaining its push behavior.

For a sibling-repository workflow, opt into AutoCloneRepositories. Same-worktree modules are discovered in place; a missing direct sibling is cloned with GitHub CLI. Published module images default to a branch-and-commit tag and add -dirty when their source worktree has changes. Registries can be modeled separately from image names, factory-created ContainerResource integrations can publish custom images while retaining their typed APIs, missing clean images can be pulled before building, and custom build outputs can be retagged directly. Each exported project or container publisher can select a separate BuildRepository and revision, so a resource may be defined in an application contract while its Dockerfile and build script remain in an owning repository. Imported modules pinned to a branch, tag, or commit use isolated managed checkouts that protect sibling and AppHost developer worktrees. The module guide documents the layout, configuration, and validation behavior.

For an ongoing feature branch that must be exercised by another repository's CI, install the local .NET tool, produce a request containing the clean pushed commit and any already-built image digests, then dispatch the consumer's trusted workflow:

dotnet tool install --global Shirubasoft.Aspire.ModularAppHosts.Tool
dotnet modular-apphosts preview produce \
  --descriptor module-preview.producer.json \
  --contract-version 2.3.0-preview.7 \
  --image catalog-api=ghcr.io/example/catalog/api@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --output module-preview.json
dotnet modular-apphosts preview trigger \
  --manifest module-preview.json \
  --repo example/end-to-end-tests \
  --workflow module-preview-e2e.yml \
  --ref main \
  --wait \
  --github-output "$GITHUB_OUTPUT"

For CI, preview workflow generate producer writes a reviewable GitHub Actions workflow that uses an attached checkout, isolated tool installs, one aggregate aspire do push <resource>... pipeline run, Docker's registry-reported digest formatter, the exact contract version, gh workflow run, and gh run watch. preview produce owns descriptor/image joining and validation. Registry and package authentication uses explicit producer-owned scripts. See the preview guide for the generator options and authentication contract.

Image-only producers can configure a trusted external AppHost repository and ref. The workflow acquires it with gh, pins the module to its exact commit, and maps each descriptor image's build repository to the producer workspace before running one resource-scoped push pipeline.

Generate the producer descriptor itself with preview descriptor generate producer --apphost ... --module ..., and run the same command with --check in CI. The command derives publisher kinds, image repositories, and the module contract package ID from the effective AppHost model and emits a descriptor linked to the shipped JSON Schema.

The request records full commits and OCI digests as its reproducible identities. The producer descriptor may omit the contract for an image-only preview, or omit only its version and receive the exact CI-computed version through --contract-version. The consumer policy decides whether the contract is required and whether to restore its exact package from a reviewed HTTPS NuGet source or pack it from a reviewed source fallback. Published-package materialization restores the reviewed package directly. Requests that carry a contract also use a package feed.

The consumer tool checks its own policy and writes a trusted resolution for ApplyModulePreviewResolutionAsync. preview trigger prints workflow_run_id and workflow_run_url; --github-output appends them to a GitHub Actions output file, while a bare --wait returns the consumer run's final status. See the cross-repository preview guide for the complete security model, package-source and source-fallback boundaries, and runnable two-repository example.

Set an exported project's run mode to Project for local debugging while keeping its portable container representation for publishing:

{
  "Aspire": {
    "ModularAppHosts": {
      "Modules": {
        "catalog": {
          "Projects": {
            "catalog-api": {
              "ProjectMode": "Project"
            }
          }
        }
      }
    }
  }
}

Guides and samples

• Module guide: module contracts, generated resources, imports, repository behavior, and image publishing.
• E2E testing guide: one test suite for AppHost and Docker Compose modes.
• Cross-repository preview guide: exact-SHA manifests, workflow dispatch, preview contracts, and security boundaries.
• Two-AppHost sample: one AppHost exports a mixed module and another imports it.
• eShop E2E sample: catalog and orders modules tested in both modes in CI.
• Image pipeline sample: effective image descriptions plus real local-registry build, push, pull, and mapping validation.
• Preview workflow sample: offline external-producer policy verification and producer workflow generation.
• Contract dependency preview sample: exact direct contract dependency generation and consumer-policy enforcement from a local feed.
• Multi-repository E2E sample: an isolated consumer builds a module image from an independently pinned Git repository without changing the producer worktree.
• Cross-repository preview producer and consumer: a producer feature branch changes source and its resource graph, then dispatches a trusted consumer E2E at the exact commit.

For repository setup, validation commands, and the release workflow, see Contributing.