User Secrets | Variáveis de Ambiente | AppSettings | CSharp

• User Secrets | Variáveis de Ambiente | AppSettings | CSharp

---

Tabela de comandos

Comando	Descrição	Exemplo
dotnet user-secrets init	Inicializa o uso de User Secrets no projeto (gera o UserSecretsId no .csproj)	dotnet user-secrets init
dotnet user-secrets set	Adiciona ou atualiza um segredo	dotnet user-secrets set "ApiKey" "minha-chave"
dotnet user-secrets set (hierárquico)	Define valores aninhados (igual ao appsettings.json)	dotnet user-secrets set "Jwt:Key" "segredo-jwt"
dotnet user-secrets list	Lista todos os segredos do projeto	dotnet user-secrets list
dotnet user-secrets get	Obtém o valor de um segredo específico	dotnet user-secrets get "ApiKey"
dotnet user-secrets remove	Remove um segredo específico	dotnet user-secrets remove "ApiKey"
dotnet user-secrets clear	Remove todos os segredos do projeto	dotnet user-secrets clear
dotnet user-secrets set (JSON)	Define valores complexos manualmente	dotnet user-secrets set "ConnectionStrings:Default" "Server=..."
dotnet user-secrets --help	Exibe ajuda e opções disponíveis	dotnet user-secrets --help

---

Visão Geral

Os User Secrets (também chamados de Secrets do .NET) são um mecanismo do .NET para armazenar informações sensíveis (como senhas, strings de conexão, tokens de API e chaves privadas) fora do código-fonte e fora do controle de versão.

Eles são usados principalmente em ambiente de desenvolvimento e não devem ser utilizados em produção.

---

Por que usar User Secrets?

Problemas comuns sem User Secrets:

• Senhas expostas no appsettings.json
• Segredos enviados para o GitHub por engano
• Necessidade de múltiplos arquivos de configuração por desenvolvedor

Benefícios dos User Secrets:

• Não ficam no repositório
• Funcionam automaticamente com o sistema de configuração do .NET
• São específicos por máquina/usuário
• Fáceis de gerenciar via CLI

---

Quando usar (e quando não usar)

Use User Secrets quando:

• Estiver em ambiente de desenvolvimento local

• Precisar armazenar:

  • Connection strings
  • Tokens de APIs externas
  • Senhas temporárias

NÃO use User Secrets quando:

• Estiver em produção
• Precisar compartilhar segredos entre servidores

👉 Em produção, use:

• Variáveis de ambiente
• Azure Key Vault
• AWS Secrets Manager
• HashiCorp Vault

---

Como o User Secrets funciona internamente

1. O projeto recebe um UserSecretsId
2. Os segredos são armazenados em um arquivo JSON fora do projeto
3. O .NET carrega esses segredos automaticamente em IConfiguration
4. Eles sobrescrevem valores do appsettings.json

Localização dos arquivos de secrets

Windows

%APPDATA%\Microsoft\UserSecrets\<UserSecretsId>\secrets.json

Linux / macOS

~/.microsoft/usersecrets/<UserSecretsId>/secrets.json

---

Habilitando User Secrets em um projeto

Opção 1: Criar projeto com suporte

Projetos como ASP.NET Core já vêm com suporte automático.

Opção 2: Habilitar manualmente

Execute no diretório do projeto:

dotnet user-secrets init

Isso adiciona ao .csproj:

<PropertyGroup>
  <UserSecretsId>c1b8a1a0-xxxx-xxxx-xxxx-xxxxxxxx</UserSecretsId>
</PropertyGroup>

---

Adicionando segredos

Via CLI

Adicionar um segredo simples:

dotnet user-secrets set "ApiKey" "minha-chave-super-secreta"

Adicionar um objeto complexo:

dotnet user-secrets set "Jwt:Key" "minha-chave-jwt"
dotnet user-secrets set "Jwt:Issuer" "MinhaEmpresa"

Via arquivo secrets.json

Exemplo de secrets.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=AppDb;User Id=sa;Password=123456;"
  },
  "ApiKey": "abc-123",
  "Jwt": {
    "Key": "segredo-jwt",
    "Issuer": "MinhaEmpresa"
  }
}

⚠️ Nunca versionar esse arquivo.

---

Lendo secrets no código

Usando IConfiguration

var apiKey = configuration["ApiKey"];
var jwtKey = configuration["Jwt:Key"];

Usando Options Pattern

Classe de configuração:

public class JwtSettings
{
    public string Key { get; set; }
    public string Issuer { get; set; }
}

Registro:

builder.Services.Configure<JwtSettings>(
    builder.Configuration.GetSection("Jwt"));

Uso:

public class MeuServico
{
    private readonly JwtSettings _settings;

    public MeuServico(IOptions<JwtSettings> options)
    {
        _settings = options.Value;
    }
}

---

Prioridade de configuração no .NET

A ordem típica de carregamento é:

1. appsettings.json
2. appsettings.{Environment}.json
3. User Secrets (somente Development)
4. Variáveis de ambiente
5. Argumentos de linha de comando

👉 O último sobrescreve os anteriores.

---

Ver, listar e remover secrets

Listar todos

dotnet user-secrets list

Remover um segredo

dotnet user-secrets remove "ApiKey"

Limpar todos

dotnet user-secrets clear

---

User Secrets e ASP.NET Core

No Program.cs, o carregamento é automático quando:

if (builder.Environment.IsDevelopment())
{
    builder.Configuration.AddUserSecrets<Program>();
}

⚠️ Em templates modernos, isso já vem configurado.

---

Segurança: o que User Secrets NÃO faz

• ❌ Não criptografa os dados
• ❌ Não protege contra acesso ao SO
• ❌ Não é seguro para produção

Eles apenas evitam exposição acidental no código e no Git.

---

Boas práticas

• Nunca usar User Secrets em produção
• Nunca commitar segredos
• Usar nomes hierárquicos (Api:Key)
• Usar Options Pattern
• Usar Azure Key Vault / Secrets Manager em produção

---

Comparação rápida

Solução	Ambiente	Seguro	Versionado
appsettings.json	Todos	❌	✅
User Secrets	Dev	⚠️	❌
Variáveis de ambiente	Todos	✅	❌
Azure Key Vault	Produção	✅	❌

---

Conclusão

Os User Secrets do .NET são a solução ideal para segredos locais de desenvolvimento, mantendo o código limpo, seguro e versionável.

Eles funcionam de forma integrada com o sistema de configuração do .NET e devem ser combinados com soluções mais robustas em produção.

---