Configuração do Aspire

O que Configuração do Aspire faz?

Quando Usar Esta Skill

Use esta skill quando:

• Conectar recursos do AppHost à configuração do aplicativo em repositórios baseados em Aspire
• Garantir que a configuração de produção seja transparente e portátil fora do Aspire
• Evitar pacotes de cliente/descoberta de serviço do Aspire dentro do código do aplicativo
• Projetar toggles de funcionalidades para dev/test sem alterar os caminhos do código do aplicativo

---

Princípios Centrais

1. AppHost é proprietário dos pacotes de infraestrutura do Aspire

   • Os pacotes de hospedagem do Aspire pertencem exclusivamente ao AppHost.
   • Os projetos do aplicativo não devem referenciar pacotes de cliente/descoberta de serviço do Aspire.

2. Apenas configuração explícita

   • O AppHost deve traduzir as saídas dos recursos em chaves de configuração explícitas (variáveis de ambiente).
   • O código do aplicativo vincula-se apenas a IOptions<T> ou Configuration.

3. Paridade e transparência com produção

   • Todo valor injetado pelo AppHost deve ser representável em produção como variáveis de ambiente ou arquivos de configuração sem o Aspire.
   • Evite descoberta de serviço opaca e configuração implícita.

---

Fluxo de Configuração

Recurso do AppHost -> WithEnvironment(...) -> chaves de configuração do app -> IOptions<T> no app

O AppHost é responsável por transformar recursos do Aspire em configurações explícitas do aplicativo. O aplicativo nunca consome clientes Aspire ou descoberta de serviço diretamente.

---

Padrões do AppHost (Mapeamento Explícito)

Exemplo: Banco de Dados + Armazenamento de Blobs

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

Pontos-chave

• WithReference(db, "Postgres") define ConnectionStrings__Postgres explicitamente.
• Toda dependência externa é representada por chaves de configuração explícitas.
• O projeto da API apenas lê valores de Configuration.

---

Padrão do Código do Aplicativo (Sem Clientes Aspire)

O código do aplicativo vincula-se a opções e inicializa SDKs diretamente. Ele nunca depende de pacotes de cliente Aspire ou descoberta de serviço.

// 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); // usa apenas opções explícitas
});

Não adicione pacotes de cliente Aspire (ou AddServiceDiscovery) ao aplicativo. Estas são preocupações de orquestração e devem permanecer no AppHost.

---

Toggles de Funcionalidades e Substituições de Teste

Mantenha os toggles na configuração e gerencie-os através do AppHost e de fixtures de teste. Isso mantém a paridade entre a configuração de dev/test e a produção.

// AppHost: desabilitar persistência em testes através de substituições de configuração
var config = builder.Configuration.GetSection("App")
    .Get<AppHostConfiguration>() ?? new AppHostConfiguration();

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

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

Consulte skills/aspire/integration-testing/SKILL.md para padrões de como passar substituições de configuração para o DistributedApplicationTestingBuilder.

---

Lista de Verificação: Faça / Não Faça

Faça

• Mapeie toda saída de recurso do Aspire para chaves de configuração explícitas
• Use IOptions<T> com validação para todas as configurações de infraestrutura
• Mantenha o AppHost como o único lugar que referencia pacotes de hospedagem do Aspire
• Garanta que qualquer valor injetado pelo AppHost possa ser definido em variáveis de ambiente de produção

Não Faça

• Referencie pacotes de cliente/descoberta de serviço do Aspire em projetos do aplicativo
• Dependa de descoberta de serviço opaca que não pode ser espelhada em produção
• Esconda a configuração por trás de abstrações exclusivas do Aspire

---

Skills Relacionadas

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

---

Recursos

• Configuração de ambiente do AppHost Aspire: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host
• Configuração no .NET: https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration