aspire

Visão geral da skill aspire

O que a skill aspire ajuda você a fazer

A skill aspire é indicada para quem precisa criar, executar, depurar, configurar ou publicar uma aplicação distribuída baseada em Aspire sem ter que montar o fluxo juntando documentação espalhada. Ela é mais útil quando o seu objetivo real não é “aprender Aspire em teoria”, mas sim “colocar um AppHost para funcionar, conectar os serviços corretamente, inspecionar falhas e preparar artefatos para deploy”.

Quem deve usar aspire

Os perfis com melhor encaixe são:

• desenvolvedores avaliando o Aspire para orquestração local de apps com múltiplos serviços
• equipes adicionando um AppHost em torno de APIs, containers ou executáveis já existentes
• usuários que querem a ajuda de um assistente de IA com aspire install, setup, troubleshooting e publicação voltada a deploy
• equipes polyglot combinando um AppHost em .NET com serviços em Python, Node.js, Go, Java ou containers

O que diferencia esta skill aspire

Esta skill aspire é mais forte do que um prompt genérico porque aponta o agente para a referência certa de acordo com a tarefa:

• uso de CLI e detalhes de instalação em references/cli-reference.md
• conceitos de AppHost e runtime em references/architecture.md
• fluxos de dashboard e observabilidade em references/dashboard.md
• orientação de publish para o alvo em references/deployment.md
• descoberta de integrações via MCP em references/integrations-catalog.md

Isso importa porque o Aspire tem um modelo mental específico: o AppHost define recursos e dependências, enquanto o runtime e o dashboard ajudam você a operá-los localmente.

Ponto principal de decisão antes de instalar aspire

Use Aspire se você quer um único lugar definido em código para orquestrar serviços, dependências, endpoints, logs, traces e artefatos de publish para uma plataforma de destino. Não escolha a ferramenta esperando fazer deploy direto em produção com um único comando: o repositório deixa claro que o Aspire publica manifests e artefatos, e o deploy real fica por conta do seu CI/CD ou da plataforma.

Como usar a skill aspire

Contexto de instalação para a skill aspire

Um caminho prático para instalar a skill aspire começa adicionando a skill e, depois, usando as referências como contexto específico para cada tarefa:

1. Instale a skill:
   npx skills add github/awesome-copilot --skill aspire
2. Abra skills/aspire/SKILL.md
3. Carregue apenas o arquivo de referência que corresponde à sua tarefa, em vez de ler tudo

Ordem de leitura sugerida:

• SKILL.md
• references/cli-reference.md
• references/architecture.md
• references/deployment.md
• references/troubleshooting.md

Como instalar o próprio Aspire

Se o seu objetivo é usar o Aspire de fato, a skill aponta para o fluxo da CLI standalone:

# Linux / macOS
curl -sSL https://aspire.dev/install.sh | bash

# Windows PowerShell
irm https://aspire.dev/install.ps1 | iex

aspire --version

Isso é importante porque a CLI do Aspire é uma interface principal, não apenas um recurso secundário do dotnet.

Comece com o enquadramento certo da tarefa

A skill aspire funciona melhor quando o seu pedido inclui uma destas intenções de forma explícita:

• criar um novo app Aspire
• adicionar um AppHost a uma solução existente
• conectar uma dependência como Redis ou PostgreSQL
• executar e depurar uma aplicação distribuída local
• publicar a saída do Aspire para Docker ou Kubernetes
• diagnosticar problemas de startup, health ou service discovery

Um pedido fraco como “ajuda com Aspire” obriga o assistente a adivinhar. Um pedido mais forte como “configure um AppHost para minha API, Redis e um worker em Python, depois prepare a saída de publish para Docker” já dá contexto suficiente para usar as referências corretas.

Quais entradas a skill aspire precisa

Para obter uma resposta de alta qualidade, informe:

• a estrutura atual do seu repositório
• linguagens e runtimes de destino
• se você já tem um AppHost
• restrições do runtime local, como disponibilidade de Docker ou Podman
• plataforma de publish desejada: Docker, Kubernetes ou saída orientada a Azure
• sintomas observados da falha, se estiver em troubleshooting

Exemplo útil de entrada:

I have a .NET API, a React frontend, and a Redis dependency. I want Aspire for local orchestration and Docker publish artifacts. I already use Docker Desktop. Show me the AppHost shape, CLI commands, and likely package choices.

Como transformar um objetivo vago em um prompt forte para aspire

Um bom prompt de orientação para aspire normalmente inclui cinco partes:

1. formato atual da aplicação
2. recursos desejados
3. expectativa para execução local
4. destino de deploy
5. formato em que você quer a resposta

Exemplo:

Use the aspire skill to propose an AppHost for:
- .NET API in src/Api
- Node frontend in src/Web
- PostgreSQL for local dev
Need:
- service startup order
- endpoint wiring
- environment variable strategy
- Aspire CLI commands
- publish path for Kubernetes
Return code snippets plus a short explanation of tradeoffs.

Arquivos do repositório para ler primeiro em uso real com aspire

Se você está avaliando a adoção da skill aspire, estes arquivos são os mais importantes:

• SKILL.md para entender escopo e roteamento
• references/cli-reference.md para instalação, aspire new, aspire run, aspire publish e comandos compatíveis com a versão
• references/deployment.md para o limite crucial entre publish e deploy
• references/polyglot-apis.md se os seus serviços não forem todos em .NET
• references/mcp-server.md se você quiser inspeção guiada por assistente e consulta de documentação
• references/troubleshooting.md se a orquestração local falhar

Essa estrutura é prática: a skill é guiada por referências, então a qualidade depende de carregar o arquivo certo, não todos os arquivos.

Como o uso de aspire funciona na prática

O uso típico de aspire segue esta ordem:

1. criar ou abrir o AppHost
2. definir recursos e referências
3. executar localmente com aspire run
4. inspecionar no dashboard o estado dos recursos, logs, endpoints e traces
5. iterar na configuração
6. publicar artefatos para o seu alvo de deploy

Esse fluxo é melhor do que pular direto para deploy, porque o Aspire é opinativo primeiro em relação à orquestração local e à observabilidade.

Como usar aspire para Deployment do jeito certo

Em aspire para Deployment, o fato mais importante é que aspire publish gera artefatos de deploy; ele não faz o deploy diretamente.

Exemplos das referências:

aspire publish -p docker -o ./docker-output
aspire publish -p kubernetes -o ./k8s-output

Dica de decisão:

• escolha Aspire se você quer que os artefatos de deploy sejam derivados do mesmo modelo de AppHost usado localmente
• não escolha se você espera uma única ferramenta que tanto defina a aplicação quanto gerencie totalmente o rollout em produção

Quando usar o caminho via MCP

A skill aspire é especialmente útil com MCP quando você quer que um assistente inspecione uma aplicação em execução ou busque documentação de integrações sem pesquisa manual.

references/mcp-server.md mostra aspire mcp init, que configura ambientes de IA compatíveis e pode criar .vscode/mcp.json além de AGENTS.md. Isso pesa na decisão de adoção porque reduz a distância entre “o assistente conhece os conceitos do Aspire” e “o assistente consegue ver meus recursos, logs e traces reais”.

Dicas práticas que melhoram materialmente a resposta

• Diga se sua carga é um .NET project, container ou executable; o Aspire modela cada um deles de forma diferente.
• Informe cedo a disponibilidade do runtime local. Apps polyglot podem exigir que o runtime da linguagem de destino esteja instalado, mesmo com AppHost em .NET.
• Peça explicitamente ordem de startup e ligação entre dependências; é aí que o valor do AppHost aparece.
• Se o objetivo final for deploy, peça ao agente para separar as escolhas de orquestração local das escolhas de publish para o alvo.
• Se um comando falhar, inclua o comando completo e o estado observado no dashboard ou nos logs, e não apenas “não funcionou”.

FAQ da skill aspire

A skill aspire é boa para iniciantes

Sim, desde que você já entenda minimamente aplicações com múltiplos serviços. A skill aspire reduz os principais pontos de atrito para iniciantes: quais comandos de CLI importam, de que o AppHost é responsável, onde verificar o comportamento do dashboard e por que publish não é a mesma coisa que deploy.

Qual é o limite da skill aspire

A skill aspire cobre orquestração local, conceitos de AppHost, descoberta de integrações, setup de MCP, fluxos de dashboard, troubleshooting e preparação de deploy orientada a publish. Ela não substitui por completo o seu CI/CD específico de plataforma, operações de cluster ou desenho de segurança em nuvem.

Como a skill aspire é melhor do que um prompt normal

Um prompt normal pode gerar orientações plausíveis, mas erradas, de setup. A skill aspire é melhor quando você precisa de:

• orientação de CLI sensível à versão
• a distinção correta entre publish e deploy
• padrões de hospedagem polyglot
• caminhos de dashboard e troubleshooting
• descoberta de integrações via ferramentas MCP

Aspire é só para equipes .NET

Não. As referências cobrem explicitamente cargas polyglot. O AppHost continua sendo baseado em .NET, mas os serviços orquestrados podem ser containers ou executáveis em outras linguagens. Isso faz do Aspire uma boa opção para stacks mistos, não apenas para soluções puramente .NET.

Quando eu não devo usar aspire

Ignore o Aspire se:

• você só precisa de uma aplicação de processo único
• sua equipe já tem um padrão de orquestração local que funciona bem
• você precisa de gerenciamento direto de deploy em produção, e não de artefatos gerados
• seu ambiente não consegue suportar os runtimes locais ou ferramentas de container exigidos

A instalação do aspire exige Docker

Nem sempre, mas muitos fluxos práticos com Aspire se beneficiam de suporte a containers. A referência de arquitetura observa que containers podem rodar em runtimes locais como Docker ou Podman, enquanto executáveis rodam como processos nativos. A exigência exata depende dos recursos que você pretende orquestrar.

Como melhorar a skill aspire

Dê à skill aspire entradas concretas de arquitetura

A forma mais rápida de melhorar os resultados da skill aspire é parar de pedir exemplos abstratos e fornecer a sua topologia real:

• nomes dos serviços
• portas ou expectativas de endpoint
• grafo de dependências
• restrições do runtime local
• plataforma-alvo de publish

Isso leva a sugestões melhores de AppHost, ligação de endpoints mais limpa e menos placeholders genéricos.

Peça saída em blocos implantáveis

Em vez de “monte um setup Aspire para mim”, peça:

• código do AppHost
• comandos de pacotes e templates
• etapas de execução local
• passos de verificação no dashboard
• comandos de publish para a plataforma-alvo

Essa estrutura acompanha a forma como o Aspire é realmente usado e deixa a resposta mais fácil de validar.

Use a pasta references de forma intencional

Para melhorar a qualidade, diga ao agente em qual fonte ele deve se basear:

• “use references/deployment.md para escolhas de publish”
• “use references/polyglot-apis.md para opções de hospedagem em Node e Python”
• “use references/troubleshooting.md para diagnosticar falha no startup”

Isso evita respostas misturadas que confundem arquitetura, comportamento do runtime e deploy.

Falha comum na skill aspire: confundir orquestração local com deploy em produção

Um dos maiores erros de adoção é assumir que o próprio Aspire faz deploy em produção. Se a primeira resposta começar a ir nessa direção, corrija imediatamente: peça artefatos de publish e, em seguida, um plano separado de handoff para CI/CD. Isso mantém o guia aspire prático e correto.

Falha comum: faltar premissas de dependência e health

Se os serviços iniciarem na ordem errada ou falharem em discovery, peça ao agente para modelar explicitamente:

• referências entre recursos
• comportamento de espera/health
• variáveis de ambiente derivadas das dependências
• necessidades de exposição de endpoints externos

É aqui que um pedido vago de uso de aspire costuma render menos do que deveria.

Melhore o troubleshooting compartilhando evidências observáveis

Quando você quiser que a skill aspire depure um problema, forneça:

• o comando aspire run usado
• o estado de cada recurso no dashboard
• logs do recurso com falha
• se a falha está relacionada a startup, conectividade ou publish

Evidência observável importa mais do que despejar muito código.

Melhore saídas de aspire para Deployment com restrições do alvo

Em aspire para Deployment, diga o que a sua plataforma espera:

• artefatos de Docker Compose
• manifests de Kubernetes
• saída compatível com Helm
• limites de configuração por ambiente
• expectativas de réplicas ou ingress

A referência de deployment mostra que a saída de publish depende do alvo, então o seu pedido também deve depender.

Itere depois da primeira resposta em vez de recomeçar

Um bom prompt de segunda rodada costuma ser:

Revise the Aspire plan using these constraints:
- frontend must stay outside Aspire
- API and worker should run under AppHost
- use PostgreSQL container locally
- produce Kubernetes publish output
- explain what must still be handled by CI/CD

Esse tipo de iteração melhora muito mais a aderência do que pedir um guia aspire novo e genérico.