Nas versões antigas do .NET, as configurações da aplicação ficavam em arquivos como web.config ou app.config, escritos em XML. Esse formato era bastante detalhado, mas também verboso e de difícil leitura, o que tornava a manutenção mais trabalhosa.
Com o .NET, a Microsoft reformulou a forma de lidar com configurações e adotou o JSON como padrão, dando origem ao appsettings.json. O JSON é mais simples, leve e fácil de ler, além de ser amplamente usado em integrações modernas.
Sempre que você cria um novo projeto ASP.NET, um arquivo appsettings.json é gerado automaticamente. Ele concentra informações como strings de conexão, chaves de API, configurações de log, entre outras.
Importante: apesar de o JSON ser o padrão, o .NET também suporta arquivos XML e INI, garantindo flexibilidade.
Nas primeiras versões do ASP.NET, a leitura do arquivo era configurada manualmente no Startup.cs. Hoje, esse processo já vem pronto através do método WebHost.CreateDefaultBuilder(args), definido no Program.cs, simplificando bastante o setup da aplicação.
Os detalhes importam
Veja como o WebHost cria a configuração:
Antes de entendermos como o appsettings.json é montado, é importante observar alguns pontos essenciais.
A variável env.EnvironmentName recebe o valor definido na variável de ambiente ASPNETCORE_ENVIRONMENT. Esse valor pode ser alterado de duas formas:
- No arquivo launchSettings.json, localizado na pasta Properties.
- Diretamente no ambiente do sistema operacional.
Se essa variável estiver definida como Development, o .NET carregará automaticamente as configurações armazenadas em User Secrets. Por fim, também serão aplicadas as configurações adicionais que podem ser passadas na inicialização do projeto.
As camadas
O AppSettings no .NET é construído em camadas (layers). Essas camadas são carregadas em sequência, pois o WebHost já vem configurado para isso por padrão.
A ordem padrão de carregamento é:
- O arquivo
appsettings.json, localizado na raiz do projeto. - O arquivo específico para o ambiente, por exemplo:
appsettings.{Environment}.json. - User Secrets (apenas quando o ambiente é
Development). - Variáveis de ambiente do sistema operacional.
- Argumentos passados na inicialização via linha de comando.
Essa ordem garante que configurações mais específicas sobrescrevam as anteriores. Embora seja possível alterar a ordem de carregamento conforme a necessidade do projeto, na prática é muito raro encontrar sistemas que façam essa modificação.
Níveis
O AppSettings funciona de forma hierárquica. Isso significa que, conforme as camadas são carregadas, os valores podem ser sobrescritos pelas configurações mais específicas.
Esse comportamento é especialmente útil para trabalhar com múltiplos ambientes (Development, Staging, Production). Assim, você pode manter valores padrão no appsettings.json e customizar apenas o que for necessário em cada ambiente.
Exemplo prático
No arquivo appsettings.json (configuração base):
{
"ConnectionStrings": {
"DefaultConnection": "Server=localhost;Database=MinhaApp;User Id=sa;Password=12345;"
},
"Logging": {
"LogLevel": {
"Default": "Information"
}
}
}
No arquivo appsettings.Development.json (sobrescrevendo apenas o necessário):
{
"ConnectionStrings": {
"DefaultConnection": "Server=localhost;Database=MinhaAppDev;User Id=dev;Password=dev123;"
},
"Logging": {
"LogLevel": {
"Default": "Debug"
}
}
}
Resultado: quando a aplicação roda no ambiente Development, ela usa a connection string e o nível de log definidos no appsettings.Development.json, substituindo os valores do arquivo base.
User Secrets
O User Secrets é um recurso do .NET que permite armazenar informações sensíveis (como strings de conexão, tokens de API e senhas) fora do projeto. Assim, esses dados não ficam visíveis no código nem entram no controle de versão (Git, por exemplo), permanecendo apenas na máquina local do desenvolvedor.
Configurando o User Secrets
Se você estiver usando o Visual Studio, pode habilitar o User Secrets facilmente:
- Clique com o botão direito no projeto.
- Selecione a opção Manage User Secrets.
Quando configurado, o .NET cria um arquivo JSON na sua máquina, no caminho:
%USERPROFILE%\AppData\Roaming\Microsoft\UserSecrets\
Além disso, o Visual Studio adiciona automaticamente ao arquivo .csproj uma chave de identificação única:
<UserSecretsId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</UserSecretsId>
Reaproveitando em vários projetos
Como o arquivo fica armazenado localmente, é possível reutilizar os mesmos segredos em diferentes projetos. Para isso, basta copiar o mesmo <UserSecretsId> para o arquivo .csproj de outro projeto:
<UserSecretsId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</UserSecretsId>
Exemplo prático
Suponha que você tenha configurado o seguinte conteúdo no seu User Secrets:
{
"ConnectionStrings": {
"DefaultConnection": "Server=localhost;Database=MinhaApp;User Id=sa;Password=12345;"
},
"ApiKeys": {
"SendGrid": "SG.xxxxx-xxxx-xxxx"
}
}
No código, você pode acessar esses valores usando a injeção de IConfiguration:
public class HomeController : Controller
{
private readonly IConfiguration _configuration;
public HomeController(IConfiguration configuration)
{
_configuration = configuration;
}
public IActionResult Index()
{
// Lendo uma connection string
var connectionString = _configuration.GetConnectionString("DefaultConnection");
// Lendo uma chave de API
var sendGridKey = _configuration["ApiKeys:SendGrid"];
ViewBag.Message = $"Conn: {connectionString} | Key: {sendGridKey}";
return View();
}
}
Dessa forma, você mantém as informações sensíveis fora do repositório e ainda consegue acessá-las de maneira simples dentro da aplicação.
Variáveis de Ambiente
O ASP.NET utiliza a variável de ambiente ASPNETCORE_ENVIRONMENT para identificar em qual ambiente a aplicação está sendo executada. Os valores mais comuns são:
DevelopmentStagingProduction
🔎 Embora você possa definir qualquer valor, é recomendado seguir esse padrão para manter consistência.
⚠️ Atenção: no Windows e macOS os valores não diferenciam maiúsculas de minúsculas, mas no Linux diferenciam. Isso pode causar problemas difíceis de identificar, então fique atento.
Alterando no Visual Studio
Dentro do Visual Studio, você pode configurar variáveis de ambiente em: Propriedades do projeto > Debug.
Sobrescrevendo configurações do appsettings.json
Uma característica poderosa do ASP.NET é que variáveis de ambiente sobrescrevem as configurações do appsettings.json.
Exemplo de appsettings.json:
Para sobrescrever uma dessas configurações, basta criar uma variável de ambiente equivalente:
Assim, quando a aplicação for iniciada, o valor da variável de ambiente substituirá o definido no arquivo appsettings.json.
👉 Para quem vem de uma stack Microsoft tradicional, isso pode parecer estranho no começo. Mas na prática, torna-se extremamente útil em ambientes modernos, principalmente em containers e cloud.
Docker
No Docker, as variáveis de ambiente podem ser definidas de duas formas:
Dockerfile
docker-compose
Azure App Service
No Azure App Service, a configuração também é simples: Acesse App Services > Seu App Service > Configuration.
Alterando Subníveis
Normalmente, os arquivos appsettings.json são bem mais complexos do que exemplos de primeiro nível. É comum encontrar estruturas aninhadas com vários subníveis de configuração.
Considere o exemplo abaixo:
A seguir veremos como sobrescrever a chave 3rdLevel em diferentes ambientes.
Docker
Para acessar subníveis dentro de variáveis de ambiente no Docker, utiliza-se o : (dois pontos) como separador.
docker-compose
Dockerfile
ENV ApplicationSettings:OneMoreLevel:3rdLevel="Changed!"
Azure App Service
Aqui está o ponto que mais exige atenção: o comportamento muda de acordo com o sistema operacional em que o App Service está rodando.
Windows
No App Service rodando em Windows, a sintaxe é a mesma do Docker: use : (dois pontos) como separador.
Linux
Já no Linux, variáveis de ambiente não aceitam : (dois pontos). Nesse caso, é necessário usar __ (dois underlines) como separador.
ApplicationSettings__OneMoreLevel__3rdLevel=Changed!
Bônus
Em alguns casos, as configurações de variáveis de ambiente no Azure App Service podem não se comportar como esperado — às vezes parecem até “bugadas”. Uma forma prática de debugar esse tipo de situação é consultar diretamente todas as variáveis de ambiente que o App Service está carregando.
Acessando via Kudu
Para visualizar as variáveis:
- Vá até App Service > Seu App Service > Advanced Tools > Go.
- O Kudu será aberto em uma nova aba.
- No menu superior, selecione a opção Environment.
Dessa forma, você terá acesso a todas as variáveis de ambiente realmente carregadas pelo App Service, permitindo confirmar se os valores definidos na Configuration foram aplicados corretamente.
Fale conosco