Guia de início rápido: criar um aplicativo ASP.NET Core com a Configuração de Aplicativo do Azure

Neste início rápido, você usará a Configuração do Aplicativo do Azure para externalizar o armazenamento e o gerenciamento das configurações do seu aplicativo para um aplicativo ASP.NET Core. ASP.NET Core cria um único objeto de configuração baseado em chave-valor usando definições de um ou mais provedores de configuração. App Configuration oferece uma biblioteca de provedor de configuração para .NET. Portanto, você pode usar a Configuração do Aplicativo como uma fonte de configuração extra para seu aplicativo. Se você tiver um aplicativo existente, para começar a usar a Configuração do aplicativo, precisará apenas de algumas pequenas alterações no código de inicialização do aplicativo.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie um gratuitamente.
• Uma loja de configuração de aplicativos, conforme mostrado no tutorial para criar uma loja.
• .NET SDK 6.0 ou posterior

Sugestão

O Azure Cloud Shell é um shell interativo e gratuito que você pode usar para executar as instruções de linha de comando neste artigo. Ele tem ferramentas comuns do Azure pré-instaladas, incluindo o SDK do .NET. Se estiver com sessão iniciada na sua subscrição do Azure, abra o Azure Cloud Shell a partir do shell.azure.com. Você pode saber mais sobre o Azure Cloud Shell lendo nossa documentação

Adicionar valores-chave

Adicione as seguintes chaves-valores à loja de Configuração do Aplicativo e deixe Etiqueta e Tipo de Conteúdo com os seus valores padrão. Para obter mais informações sobre como adicionar valores-chave a uma loja usando o portal do Azure ou a CLI, vá para Criar um valor-chave.

Chave	Valor
TestApp:Configurações:BackgroundColor	Branco
TestApp:Configurações:FontColor	preto
TestApp:Configurações:FontSize	24
TestApp:Configurações:Mensagem	Dados da Configuração do Aplicativo do Azure

Criar um aplicativo Web ASP.NET Core

Use a interface de linha de comando (CLI) do .NET para criar um novo projeto de aplicativo Web ASP.NET Core. O Azure Cloud Shell fornece essas ferramentas para você. Eles também estão disponíveis nas plataformas Windows, macOS e Linux.

Execute o seguinte comando para criar um aplicativo Web ASP.NET Core em uma nova pasta TestAppConfig :

dotnet new webapp --output TestAppConfig

Conectar-se à App Configuration Store

Conecte-se à sua loja de Configuração de Aplicativos usando o Microsoft Entra ID (recomendado) ou uma string de conexão.

1. Navegue até o diretório TestAppconfig do projeto e execute o seguinte comando para adicionar referências de pacote NuGet.

   Microsoft Entra ID (recomendado)

   dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
   dotnet add package Azure.Identity
   

   Cadeia de conexão

   dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore
   

2. Crie um segredo de usuário para o aplicativo navegando até a pasta TestAppConfig e executando o seguinte comando.

   Microsoft Entra ID (recomendado)

   O comando usa o Gerenciador Secreto para armazenar um segredo chamado Endpoints:AppConfiguration, que armazena o ponto de extremidade da sua loja de Configuração de Aplicativos. Substitua o espaço reservado <your-App-Configuration-endpoint> pelo ponto de extremidade da sua loja de Configuração de Aplicativos. Você pode encontrar o ponto de extremidade na folha Visão geral da sua loja de Configuração de Aplicativo no portal do Azure.

   dotnet user-secrets init
   dotnet user-secrets set Endpoints:AppConfiguration "<your-App-Configuration-endpoint>"
   

   Cadeia de conexão

   O comando usa o Gerenciador Secreto para armazenar um segredo chamado ConnectionStrings:AppConfiguration, que armazena a cadeia de conexão para sua loja de configuração de aplicativos. Substitua o espaço reservado <your-App-Configuration-connection-string> pela cadeia de conexão somente leitura da App Configuration Store. Você pode encontrar a cadeia de conexão nas configurações de acesso da sua loja de Configuração de Aplicativo no portal do Azure.

   dotnet user-secrets init
   dotnet user-secrets set ConnectionStrings:AppConfiguration "<your-App-Configuration-connection-string>"
   

   Sugestão

   Alguns shells truncarão a cadeia de conexão, a menos que ela esteja entre aspas. Assegure-se de que a saída do comando dotnet user-secrets list mostre toda a cadeia de conexão. Caso contrário, execute novamente o comando, colocando a cadeia de conexão entre aspas.

   O Secret Manager armazena o segredo fora da árvore do projeto, o que ajuda a evitar o compartilhamento acidental de segredos dentro do código-fonte. Ele é usado apenas para testar o aplicativo Web localmente. Quando o aplicativo é implantado no Azure como o Serviço de Aplicativo, use as cadeias de conexão, Configurações do aplicativo ou variáveis de ambiente para armazenar a cadeia de conexão. Como alternativa, para evitar cadeias de conexão todas juntas, você pode se conectar à Configuração do Aplicativo usando identidades gerenciadas ou outras identidades do Microsoft Entra.

3. Abra Program.cs e adicione os seguintes namespaces:

   Microsoft Entra ID (recomendado)

   using Microsoft.Extensions.Configuration;
   using Microsoft.Azure.AppConfiguration.AspNetCore;
   using Azure.Identity;
   

   Cadeia de conexão

   using Microsoft.Extensions.Configuration;
   using Microsoft.Azure.AppConfiguration.AspNetCore;
   

4. Conecte-se à sua App Configuration Store chamando o AddAzureAppConfiguration método no Program.cs arquivo.

   Microsoft Entra ID (recomendado)

   Você usa o DefaultAzureCredential para autenticar na sua loja de configuração de aplicativos. Siga as instruções para atribuir à sua credencial a função de Leitor de Dados de Configuração do Aplicativo. Certifique-se de dar tempo suficiente para que a permissão se propague antes de executar seu aplicativo.

   var builder = WebApplication.CreateBuilder(args); 
   
   // Retrieve the endpoint
   string endpoint = builder.Configuration.GetValue<string>("Endpoints:AppConfiguration")
       ?? throw new InvalidOperationException("The setting `Endpoints:AppConfiguration` was not found.");
   
   // Load configuration from Azure App Configuration 
   builder.Configuration.AddAzureAppConfiguration(options =>
   {
       options.Connect(new Uri(endpoint), new DefaultAzureCredential());
   });
   
   // The rest of existing code in program.cs
   // ... ...    
   

   Cadeia de conexão

   var builder = WebApplication.CreateBuilder(args);
   
   // Retrieve the connection string
   string connectionString = builder.Configuration.GetConnectionString("AppConfiguration")
       ?? throw new InvalidOperationException("The connection string 'AppConfiguration' was not found.");
   
   // Load configuration from Azure App Configuration
   builder.Configuration.AddAzureAppConfiguration(connectionString);
   
   // The rest of existing code in program.cs
   // ... ...
   

   Esse código carrega todos os valores-chave que não têm rótulo da sua loja de configuração de aplicativos. Para obter mais informações sobre como carregar dados da Configuração do Aplicativo, consulte a Referência da API do provedor de Configuração do Aplicativo.

Leia na App Configuration Store

Neste exemplo, você atualizará uma página da Web para exibir seu conteúdo usando as configurações definidas na sua loja de Configuração de Aplicativos.

1. Adicione um arquivo Settings.cs na raiz do diretório do projeto. Ele define uma classe fortemente tipificada Settings para a configuração que irá utilizar. Substitua o namespace pelo nome do seu projeto.

   namespace TestAppConfig
   {
       public class Settings
       {
           public string BackgroundColor { get; set; }
           public long FontSize { get; set; }
           public string FontColor { get; set; }
           public string Message { get; set; }
       }
   }
   

2. Vincule a seção de configuração TestApp:Settings ao objeto Settings.

   Atualize Program.cs com o código a seguir e adicione o TestAppConfig namespace no início do arquivo.

   using TestAppConfig;
   
   // Existing code in Program.cs
   // ... ...
   
   builder.Services.AddRazorPages();
   
   // Bind configuration "TestApp:Settings" section to the Settings object
   builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));
   
   var app = builder.Build();
   
   // The rest of existing code in program.cs
   // ... ...
   

3. Abra Index.cshtml.cs no diretório Pages e atualize a IndexModel classe com o código a seguir. Adicione o using Microsoft.Extensions.Options namespace no início do arquivo, se ele ainda não estiver lá.

   public class IndexModel : PageModel
   {
       private readonly ILogger<IndexModel> _logger;
   
       public Settings Settings { get; }
   
       public IndexModel(IOptionsSnapshot<Settings> options, ILogger<IndexModel> logger)
       {
           Settings = options.Value;
           _logger = logger;
       }
   }
   

4. Abra Index.cshtml no diretório Pages e atualize o conteúdo com o código a seguir.

   @page
   @model IndexModel
   @{
       ViewData["Title"] = "Home page";
   }
   
   <style>
       body {
           background-color: @Model.Settings.BackgroundColor;
       }
   
       h1 {
           color: @Model.Settings.FontColor;
           font-size: @(Model.Settings.FontSize)px;
       }
   </style>
   
   <h1>@Model.Settings.Message</h1>
   

Crie e execute o aplicativo localmente

1. Para criar o aplicativo usando a CLI do .NET, navegue até o diretório raiz do seu projeto. Execute o seguinte comando no shell de comando:

   dotnet build
   

2. Depois que a compilação for concluída com êxito, execute o seguinte comando para executar o aplicativo Web localmente:

   dotnet run
   

3. A saída do dotnet run comando contém duas URLs. Abra um navegador e navegue até qualquer um desses URLs para acessar seu aplicativo. Por exemplo: https://localhost:5001.

   Se estiver a trabalhar no Azure Cloud Shell, selecione o botão Pré-visualização Web seguido de Configuração. Quando solicitado a configurar a porta para visualização, digite 5000 e selecione Abrir e navegar.

   

   A página da Web tem esta aparência:

Limpeza de recursos

Se não quiser continuar a utilizar os recursos criados neste artigo, elimine o grupo de recursos que criou aqui para evitar cobranças.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são excluídos permanentemente. Certifique-se de não excluir acidentalmente o grupo de recursos ou recursos errados. Se você criou os recursos para este artigo dentro de um grupo de recursos que contém outros recursos que deseja manter, exclua cada recurso individualmente de seu respetivo painel em vez de excluir o grupo de recursos.

1. Entre no portal do Azure e selecione Grupos de recursos.
2. Na caixa Filtrar por nome, introduza o nome do seu grupo de recursos.
3. Na lista de resultados, selecione o nome do grupo de recursos para ver uma visão geral.
4. Selecione Eliminar grupo de recursos.
5. É-lhe pedido que confirme a eliminação do grupo de recursos. Insira o nome do grupo de recursos a ser confirmado e selecione Excluir.

Após alguns momentos, o grupo de recursos e todos os seus recursos são excluídos.

Próximos passos

Neste guia de início rápido, você irá:

• Provisionada uma nova loja de configuração de aplicativos.
• Ligação ao seu repositório de Configuração de Aplicações usando a biblioteca do fornecedor de configuração de aplicações.
• Leia os valores-chave da sua loja de configurações de aplicativos com a biblioteca do provedor de configuração.
• Exibida uma página da Web usando as configurações definidas na sua loja de configuração de aplicativos.

Para saber como configurar seu aplicativo Web ASP.NET Core para atualizar dinamicamente as definições de configuração, continue para o próximo tutorial.

Ativar configuração dinâmica