Criando o projeto e launchSettings.json

Resumo

Antes de escrever qualquer endpoint, você precisa de um projeto Web API bem configurado. Aqui criamos o projeto Catalog.Api com a .NET CLI e entendemos o launchSettings.json, que controla apenas como a aplicação é iniciada na sua máquina de desenvolvimento.

1. Objetivos de Aprendizagem#

Ao final deste tópico você será capaz de:

• Criar um projeto ASP.NET Core Web API usando a .NET CLI direcionado a net9.0.
• Explicar o papel de cada arquivo gerado pelo template.
• Interpretar e ajustar os perfis de execução do launchSettings.json.
• Distinguir configuração de desenvolvimento (só sua máquina) de configuração de aplicação (appsettings.json).

2. Pré-requisitos#

• .NET SDK 9 instalado (dotnet --version deve retornar 9.x).
• Um editor (Visual Studio, VS Code ou Rider).

3. Conceito#

O ASP.NET Core não usa mais web.config como fonte principal de configuração. Um projeto Web API é um simples aplicativo de console que sobe um servidor web (Kestrel) e registra serviços em um contêiner de injeção de dependência.

O porquê de começarmos pela CLI: ela é idêntica em qualquer sistema operacional e é o que roda no seu pipeline de CI/CD. Entender a CLI significa entender o que a IDE faz por baixo dos panos.

O launchSettings.json fica em Properties/ e só existe em desenvolvimento — ele nunca é publicado. Ele descreve perfis de inicialização: qual servidor usar, quais variáveis de ambiente definir e qual URL abrir.

4. Mão na Massa#

4.1. Setup#

Crie a solução e o projeto:

dotnet new sln -n Catalog
dotnet new webapi -n Catalog.Api -f net9.0 --use-controllers
dotnet sln add Catalog.Api/Catalog.Api.csproj

Nota

a partir do template atual, dotnet new webapi gera Minimal APIs por padrão. O flag --use-controllers gera a estrutura baseada em Controllers, que é a que usaremos ao longo do curso.

Confira o Target Framework em Catalog.Api/Catalog.Api.csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

4.2. Implementação Passo a Passo#

1. Abra Properties/launchSettings.json. Ele se parece com:

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

2. commandName define o servidor: Project sobe o Kestrel diretamente; IISExpress usa o IIS Express.
3. ASPNETCORE_ENVIRONMENT define o ambiente. É a chave que separa comportamento de dev e produção.
4. Escolha um perfil ao rodar: dotnet run --launch-profile https.

4.3. Executando#

cd Catalog.Api
dotnet run --launch-profile http

Você verá no terminal Now listening on: http://localhost:5000. A aplicação está no ar.

5. Exemplo Completo#

Properties/launchSettings.json enxuto para o curso (apenas Kestrel, sem abrir o navegador):

{
  "$schema": "https://json.schemastore.org/launchsettings.json",
  "profiles": {
    "CatalogApi": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

6. Boas Práticas e Armadilhas#

Atenção

nunca coloque connection strings de produção ou segredos no launchSettings.json. Ele não é criptografado nem publicado; use user-secrets em dev e variáveis de ambiente/secret store em produção (ver Módulo 13).

7. Segurança e Produção#

• Em produção o launchSettings.json é irrelevante: o ambiente vem da variável ASPNETCORE_ENVIRONMENT definida no host.
• Nunca envie a aplicação para produção com ASPNETCORE_ENVIRONMENT=Development — isso pode expor páginas de erro detalhadas.

8. Exercícios#

• Fácil: crie um segundo perfil chamado CatalogApi-Prod-Local com ASPNETCORE_ENVIRONMENT=Production.
• Médio: rode o projeto pelos dois perfis e observe a diferença nas mensagens de log de inicialização.
• Desafio: remova o launchSettings.json e inicie a aplicação definindo a porta e o ambiente apenas por variáveis de ambiente do terminal. Explique por que continua funcionando.

9. Resumo#

Criamos Catalog.Api direcionado a net9.0 com Controllers e entendemos que o launchSettings.json controla somente a inicialização em dev. O ambiente é definido por ASPNETCORE_ENVIRONMENT, a peça central para comportamento condicional.

10. Próximos Passos#

No próximo tópico exploramos o Program.cs, o registro de serviços e os métodos de extensão que mantêm essa classe limpa.

11. Referências#

• Microsoft Learn — Criar uma Web API com ASP.NET Core
• Microsoft Learn — dotnet new
• Microsoft Learn — Uso de múltiplos ambientes no ASP.NET Core