Index of every page on this site: llms.txt
All skills
wshaddix avatar

/aspire-configuration

@09da68d
Run it yourself

Configure Aspire AppHost to emit explicit app config via environment variables while keeping app code free of Aspire clients and service discovery. Use when wiring AppHost resources to application configuration, ensuring production configuration is transparent and portable outside of Aspire, or avoiding Aspire client packages inside application code.

Use this Skill: https://skilld.dev/gh/wshaddix/dotnet-skills/aspire-configuration

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈94 tokens for metadata: the name and description. ≈1.2k when used: this file.

Description uses 4.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈375 characters, or 4.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Aspire Configuration

When to Use This Skill

Use this skill when:

  • Wiring AppHost resources to application configuration in Aspire-based repos
  • Ensuring production configuration is transparent and portable outside of Aspire
  • Avoiding Aspire client/service-discovery packages inside application code
  • Designing feature toggles for dev/test without changing app code paths

Core Principles

  1. AppHost owns Aspire infrastructure packages

    • Aspire Hosting packages belong in AppHost only.
    • App projects should not reference Aspire client/service-discovery packages.
  2. Explicit configuration only

    • AppHost must translate resource outputs into explicit config keys (env vars).
    • App code binds to IOptions<T> or Configuration only.
  3. Production parity and transparency

    • Every value injected by AppHost must be representable in production as env vars or config files without Aspire.
    • Avoid opaque service discovery and implicit configuration.

Configuration Flow

AppHost resource -> WithEnvironment(...) -> app config keys -> IOptions<T> in app

The AppHost is responsible for turning Aspire resources into explicit app settings. The application never consumes Aspire clients or service discovery directly.


AppHost Patterns (Explicit Mapping)

Example: Database + Blob Storage

// AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("appdb");

var minio = builder.AddContainer("minio", "minio/minio")
    .WithArgs("server", "/data")
    .WithHttpEndpoint(targetPort: 9000, name: "http")
    .WithHttpEndpoint(targetPort: 9001, name: "console")
    .WithEnvironment("MINIO_ROOT_USER", "minioadmin")
    .WithEnvironment("MINIO_ROOT_PASSWORD", "minioadmin");

var api = builder.AddProject<Projects.MyApp_Api>("api")
    .WithReference(db, "Postgres")
    .WithEnvironment("BlobStorage__Enabled", "true")
    .WithEnvironment("BlobStorage__ServiceUrl", minio.GetEndpoint("http"))
    .WithEnvironment("BlobStorage__AccessKey", "minioadmin")
    .WithEnvironment("BlobStorage__SecretKey", "minioadmin")
    .WithEnvironment("BlobStorage__Bucket", "attachments")
    .WithEnvironment("BlobStorage__ForcePathStyle", "true");

builder.Build().Run();

Key points

  • WithReference(db, "Postgres") sets ConnectionStrings__Postgres explicitly.
  • Every external dependency is represented via explicit config keys.
  • The API project only reads Configuration values.

App Code Pattern (No Aspire Clients)

Application code binds to options and initializes SDKs directly. It never depends on Aspire client packages or service discovery.

// Api/Program.cs
builder.Services
    .AddOptions<BlobStorageOptions>()
    .BindConfiguration("BlobStorage")
    .ValidateDataAnnotations()
    .ValidateOnStart();

builder.Services.AddSingleton<IBlobStorageService>(sp =>
{
    var options = sp.GetRequiredService<IOptions<BlobStorageOptions>>().Value;
    return new S3BlobStorageService(options); // uses explicit options only
});

Do not add Aspire client packages (or AddServiceDiscovery) to the app. Those are orchestration concerns and should stay in AppHost.


Feature Toggles and Test Overrides

Keep toggles in config and drive them through AppHost and test fixtures. This maintains parity between dev/test and production configuration.

// AppHost: disable persistence in tests via config overrides
var config = builder.Configuration.GetSection("App")
    .Get<AppHostConfiguration>() ?? new AppHostConfiguration();

if (!config.UseVolumes)
{
    postgres.WithDataVolume(false);
}

api.WithEnvironment("BlobStorage__Enabled", config.EnableBlobStorage.ToString());

See skills/aspire/integration-testing/SKILL.md for patterns on passing configuration overrides into DistributedApplicationTestingBuilder.


Do / Don’t Checklist

Do

  • Map every Aspire resource output to explicit configuration keys
  • Use IOptions<T> with validation for all infrastructure settings
  • Keep AppHost as the only place that references Aspire hosting packages
  • Ensure any AppHost-injected value can be set in production env vars

Don’t

  • Reference Aspire client/service-discovery packages in application projects
  • Rely on opaque service discovery that cannot be mirrored in production
  • Hide configuration behind Aspire-only abstractions

Related Skills

  • skills/aspire/service-defaults/SKILL.md
  • skills/aspire/integration-testing/SKILL.md
  • skills/akka/aspire-configuration/SKILL.md

Resources

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides architectural guidance and best practices for .NET Aspire configuration. It promotes explicit environment variable configuration and separation of orchestration from application code. No malicious patterns detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

Signed by skilld at 09da68d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Dormantupdated 9 months ago

README badge

README badge for wshaddix/dotnet-skills/aspire-configuration