Aspire-Konfiguration

Was macht Aspire-Konfiguration?

Wann dieses Skill verwendet werden soll

Verwende dieses Skill, wenn:

• AppHost-Ressourcen mit der Anwendungskonfiguration in Aspire-basierten Repos verbunden werden
• Sichergestellt werden soll, dass die Produktionskonfiguration transparent und außerhalb von Aspire portabel ist
• Aspire-Client-/Service-Discovery-Pakete im Anwendungscode vermieden werden sollen
• Feature-Toggles für Entwicklungs-/Testumgebungen entworfen werden, ohne die Anwendungspfade zu ändern

---

Kernprinzipien

1. AppHost besitzt Aspire-Infrastrukturpakete

   • Aspire-Hosting-Pakete gehören ausschließlich in den AppHost.
   • App-Projekte sollten keine Aspire-Client-/Service-Discovery-Pakete referenzieren.

2. Nur explizite Konfiguration

   • Der AppHost muss Ressourcenausgaben in explizite Konfigurationsschlüssel (Umgebungsvariablen) übersetzen.
   • Der Anwendungscode bindet nur an IOptions<T> oder Configuration.

3. Produktionsparität und Transparenz

   • Jeder vom AppHost injizierte Wert muss in der Produktion als Umgebungsvariable oder Konfigurationsdatei ohne Aspire darstellbar sein.
   • Vermeide undurchsichtige Service Discovery und implizite Konfiguration.

---

Konfigurationsablauf

AppHost-Ressource -> WithEnvironment(...) -> App-Konfigurationsschlüssel -> IOptions<T> in der App

Der AppHost ist dafür verantwortlich, Aspire-Ressourcen in explizite App-Einstellungen umzuwandeln. Die Anwendung nutzt niemals direkt Aspire-Clients oder Service Discovery.

---

AppHost-Muster (Explizites Mapping)

Beispiel: Datenbank + Blob-Speicher

// 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();

Wichtige Punkte

• WithReference(db, "Postgres") setzt ConnectionStrings__Postgres explizit.
• Jede externe Abhängigkeit wird über explizite Konfigurationsschlüssel dargestellt.
• Das API-Projekt liest nur Configuration-Werte.

---

App-Code-Muster (Keine Aspire-Clients)

Der Anwendungscode bindet an Optionen und initialisiert SDKs direkt. Er hängt niemals von Aspire-Client-Paketen oder Service Discovery ab.

// 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); // verwendet nur explizite Optionen
});

Füge keine Aspire-Client-Pakete (oder AddServiceDiscovery) zur App hinzu. Diese gehören zu den Orchestrierungsbelangen und sollten im AppHost bleiben.

---

Feature-Toggles und Test-Überschreibungen

Halte Toggles in der Konfiguration und steuere sie über AppHost und Test-Fixtures. Dies bewahrt die Parität zwischen Entwicklungs-/Test- und Produktionskonfiguration.

// AppHost: Deaktiviere Persistenz in Tests über Konfigurationsüberschreibungen
var config = builder.Configuration.GetSection("App")
    .Get<AppHostConfiguration>() ?? new AppHostConfiguration();

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

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

Siehe skills/aspire/integration-testing/SKILL.md für Muster, um Konfigurationsüberschreibungen an DistributedApplicationTestingBuilder zu übergeben.

---

Do's und Don'ts-Checkliste

Do's

• Bilde jede Aspire-Ressourcenausgabe auf explizite Konfigurationsschlüssel ab
• Verwende IOptions<T> mit Validierung für alle Infrastruktureinstellungen
• Halte AppHost als einzigen Ort, der Aspire-Hosting-Pakete referenziert
• Stelle sicher, dass jeder vom AppHost injizierte Wert in Produktionsumgebungsvariablen gesetzt werden kann

Don'ts

• Referenziere Aspire-Client-/Service-Discovery-Pakete in Anwendungsprojekten
• Verlasse dich auf undurchsichtige Service Discovery, die nicht in der Produktion gespiegelt werden kann
• Verstecke Konfiguration hinter Aspire-only-Abstraktionen

---

Verwandte Skills

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

---

Ressourcen

• Aspire AppHost-Umgebungskonfiguration: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host
• Konfiguration in .NET: https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration