Configurando .NET Aspire no Linux

Instalando o Aspire CLI

[0:48 - 2:20] Tim começa em aspire.dev, notando que o projeto recentemente foi rebatizado de "Aspire.NET" para apenas "Aspire". O renomeamento reflete o escopo expandido da ferramenta: enquanto Aspire ainda é construído em .NET e serve principalmente desenvolvedores .NET, agora suporta também hosts de aplicativos TypeScript, e mais integrações de idiomas estão no roteiro.

A instalação em si é um único comando bash copiado da documentação Aspire para a versão 9.2:

dotnet tool install -g aspirate

dotnet tool install -g aspirate

Após executar o instalador, reinicie sua sessão de terminal para que a ferramenta seja registrada no seu PATH. Sem a reinicialização, seu shell não reconhecerá o novo comando.

Em seguida, confirme que a instalação foi concluída corretamente:

aspire --version

aspire --version

Se o número da versão for impresso, o CLI está pronto. Esse processo em duas etapas (instalar, verificar) é toda a configuração do lado do terminal.

Configurando a Extensão VS Code

[2:23 - 3:30] With the CLI installed, the next step is the VS Code extension. Abra o painel de Extensões, procure por "Aspire", e instale a extensão oficial publicada pela Microsoft. A extensão adiciona estruturação de projeto, suporte de configuração de lançamento e integração com o painel Aspire.

Após a instalação, o VS Code executa uma etapa de verificação para confirmar que o CLI e a extensão estão alinhados. Tim observa que a extensão também pode estruturar um novo projeto diretamente através do palette de comandos, embora ele opte por usar a abordagem CLI em vez disso. Essa escolha é deliberada: conhecer o CLI significa que você nunca fica preso quando uma ferramenta GUI não se comporta. Quando o picker de templates do VS Code não conseguiu mostrar templates Aspire após a instalação, o CLI proporcionou uma solução imediata.

Estruturando o Projeto Inicial

[3:30 - 6:42] Em vez de usar o comando "Criar Novo Projeto .NET" do VS Code (que falhou de forma intermitente em descobrir os templates Aspire), Tim desce para o terminal e executa:

aspire new

aspire new

Várias escolhas de template aparecem no prompt interativo. Para um aplicativo de produção, você normalmente selecionaria o host de aplicativo C# vazio e construiria a partir daí. Para fins de aprendizado, Tim seleciona o Aplicativo Inicial, que gera uma frente Blazor com uma API mínima como backend. O template inicial inclui um endpoint de previsão do tempo, uma página de contador e verificações de integridade pré-conectadas, dando a você algo funcional para explorar imediatamente.

Prompts subsequentes percorrem a configuração restante:

Nome do projeto:         TinyTicket
Caminho de saída:          TinyTicket
Usar localhost de desenvolvimento:    Sim
Cache Redis:          Não
Projeto de teste:         Não
Ambiente de agente AI: Não

Tim mantém todos os recursos opcionais desligados para minimizar a complexidade. O objetivo é um ponto de partida enxuto que episódios futuros irão construir incrementalmente. Uma vez que a estruturação esteja completa, abra a pasta no VS Code e confie no workspace quando solicitado.

Entendendo a Estrutura do Projeto

[6:42 - 10:00] A solução gerada contém quatro projetos, e os relacionamentos entre eles revelam como o Aspire funciona. O projeto Host do Aplicativo é a camada de orquestração. Seu Program.cs é aproximadamente doze linhas de código:

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.TinyTicket_ApiService>("api")
    .WithHttpHealthCheck("/health");

builder.AddProject<Projects.TinyTicket_Web>("frontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(api)
    .WaitFor(api);

builder.Build().Run();

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.TinyTicket_ApiService>("api")
    .WithHttpHealthCheck("/health");

builder.AddProject<Projects.TinyTicket_Web>("frontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(api)
    .WaitFor(api);

builder.Build().Run();

Observe como a frente declara uma referência para a API e espera que ela se torne saudável antes de iniciar. Essa ordenação de dependências, descoberta de serviço e verificação de saúde é tudo que Aspire fornece a nível de código. Não há magia oculta além do que você vê neste arquivo.

Ao lado do host do aplicativo está o projeto Padrões de Serviço, que contém métodos de extensão para telemetria, logging estruturado e registro de verificação de saúde. Estas são conveniências optativas: se você ainda não tiver configurado pontos de terminação OpenTelemetry ou de verificação de saúde em seus serviços, os padrões os conectam para você.

O projeto Serviço API tem um único endpoint que retorna previsões do tempo geradas aleatoriamente. O projeto Web é uma aplicação Blazor que chama a API através de um HttpClient configurado com apenas um nome de serviço ("api"). Aspire resolve esse nome para o URL correto em tempo de execução, então o aplicativo Blazor nunca codifica um número de porta ou nome de host.

Tim destaca um detalhe importante de implantação: o próprio Aspire não é implantado em produção. A orquestração é uma ferramenta de tempo de desenvolvimento. Em produção, os URLs de serviço vêm da configuração (variáveis de ambiente, configurações de aplicativo, ou um pipeline de implantação), e os aplicativos funcionam independentemente sem o host do aplicativo.

Executando e Explorando o Painel

[10:59 - 14:46] Inicie o host do aplicativo através do painel Run and Debug no VS Code, selecionando o perfil de lançamento HTTPS. Após a restauração inicial e a construção, o painel Aspire é aberto no navegador. A primeira vez que você se conectar, você precisará colar um token de login da saída do terminal.

O painel apresenta quatro categorias de dados de observabilidade sem qualquer configuração adicional:

Saída do console agrega stdout de cada serviço em uma única visão. Em vez de alternar entre abas do terminal, você vê toda a saída intercalada e filtrável por serviço.

Logs estruturados exibem entradas de log com suas propriedades estruturadas intactas. O aviso de confiança do certificado que Tim encontra, por exemplo, aparece aqui com o contexto completo sobre qual serviço o gerou e em que nível de gravidade.

Traços mostram cadeias de chamadas distribuídas. Quando a frente Blazor solicita dados meteorológicos, o traço mostra o HTTP GET da frente, a passagem para o serviço API (que levou 7,35 milissegundos no vídeo), e o tempo total de renderização da página. Tim aponta que os números absolutos importam menos que as comparações relativas: se uma chamada normalmente leva 5 segundos e de repente leva 10, você encontrou sua regressão sem conectar um profiler.

Métricas fornecem contadores por serviço para taxas de solicitação, taxas de erro e consumo de recursos. O painel também expõe variáveis de ambiente e credenciais de endpoint para cada serviço, o que é útil para verificar se os valores de configuração estão fluindo corretamente.

Apresentando Tiny Ticket: O Projeto da Série

[14:46 - 17:17] Tim descreve o plano para o projeto que irá preencher o restante da série. Tiny Ticket é um aplicativo de help desk despojado: usuários enviam tickets de suporte, e o sistema rastreia a prioridade e o status. O modelo de dados pode ser tão pequeno quanto uma única tabela SQL. O objetivo não é construir um produto rico em recursos, mas criar uma fatia vertical que toque cada parte do ciclo de vida do desenvolvimento no Linux: construir, testar, implantar e conectar a serviços externos.

As páginas de previsão do tempo e contador do template inicial serão substituídas por visualizações de tickets, mas a orquestração Aspire, o padrão de API para frontend, e os padrões de serviço permanecerão. Futuros episódios irão adicionar Microsoft SQL Server como banco de dados, com Tim abordando uma objeção comum: desenvolvedores que não podem executar SQL Server localmente (processadores ARM, por exemplo) às vezes buscam por um banco de dados diferente. Sua resposta é que o ambiente de desenvolvimento deve replicar a produção. Se o banco de dados de produção é SQL Server, o ambiente de desenvolvimento precisa corresponder, mesmo que isso signifique executar o banco de dados em um container.

Concluindo: Do Zero ao Painel

[17:17 - 18:20] Em menos de vinte minutos, o vídeo cobre a configuração completa do Aspire no Linux: instalação do CLI, extensão VS Code, projeto estruturado e um painel que fornece log estruturado, traço distribuído e métricas sem configuração personalizada. O verdadeiro valor do Aspire não é nenhum recurso individual, mas a redução do atrito: um processo para lançar, um painel para monitorar, e um lugar para ver como os serviços interagem.

Conclusão

[18:20 - 18:53] Configurar Aspire no Linux requer a ferramenta CLI, a extensão VS Code e um projeto estruturado. A partir daí, o painel fornece observabilidade em todos os serviços sem escrever código de telemetria. O arquivo de host do aplicativo define seu gráfico de serviço em uma dúzia de linhas, e os padrões de serviço lidam com a canalização que você configuraria manualmente.

O projeto Tiny Ticket introduzido aqui servirá como base para episódios futuros sobre integração de banco de dados, implantação no Azure e fluxos de trabalho multiplataforma. Seguir esse ponto de partida significa que cada novo conceito se constrói sobre a infraestrutura que você já verificou.

Navegação da série: Este artigo é parte da série C# no Linux construindo o aplicativo Tiny Ticket. Anterior: SQL Server no Docker no Linux. Next: Adding Swagger UI to .NET Aspire on Linux.

Dica de Exemplo: Quando o seletor de modelo do VS Code falhar em descobrir modelos Aspire após a instalação da extensão, use aspire new a partir do terminal como uma alternativa confiável e, em seguida, reinicie o VS Code depois para sincronizar o estado da extensão.

Assista o vídeo completo vídeo em seu Canal no YouTube e obtenha mais insights sobre como configurar o .NET Aspire para desenvolvimento no Linux.