Conectar-se e consultar o Banco de Dados SQL do Azure usando o .NET e o Entity Framework Core

Aplica-se a: do Banco de Dados SQL do Azure

Este quickstart descreve como ligar uma aplicação a uma base de dados no Base de Dados SQL do Azure e realizar consultas usando .NET e Entity Framework Core. Este início rápido segue a abordagem sem senha recomendada para se conectar ao banco de dados. Para saber mais sobre ligações sem palavra-passe, consulte o hub sem palavra-passe.

Pré-requisitos

• Uma assinatura do Azure.
• Um banco de dados SQL configurado para autenticação com o Microsoft Entra ID (anteriormente Azure Ative Directory). Pode criar uma usando o Quickstart: Crie uma base de dados única - Base de Dados SQL do Azure.
• .NET 10.0 ou posterior.
• Visual Studio ou posterior com a carga de trabalho de ASP.NET e Desenvolvimento Web.
• A versão mais recente do CLI do Azure.
• A versão mais recente das ferramentas principais do Entity Framework:
  • Os usuários do Visual Studio devem instalar as ferramentas do Console do Gerenciador de Pacotes para o Entity Framework Core.
  • Utilizadores da linha de comandos do .NET devem instalar as ferramentas CLI para o .NET do para o Entity Framework Core.

Configurar o servidor de banco de dados

Conexões seguras e sem senha com o Banco de Dados SQL do Azure exigem determinadas configurações de banco de dados. Verifique as seguintes configurações em seu servidor lógico no Azure para se conectar corretamente ao Banco de Dados SQL do Azure em ambientes locais e hospedados:

1. Para ligações de desenvolvimento local, certifique-se de que o seu servidor lógico SQL do Azure está configurado para permitir que o endereço IP da sua máquina local e outros serviços Azure se conectem:

   1. No portal Azure, no menu de recursos, em Segurança, selecione Redes.

   2. Selecione o botão Redes selecionadas para mostrar opções de configuração adicionais.

   3. Selecione Adicionar o endereço IPv4 do cliente (xx.xx.xx.xx) para adicionar uma regra de firewall que habilitará conexões do endereço IPv4 da máquina local. Como alternativa, você também pode selecionar + Adicionar uma regra de firewall para inserir um endereço IP específico à sua escolha.

   4. Verifique se a caixa de seleção Permitir que os serviços e recursos do Azure acessem este servidor está marcada.

      

      Advertência

      Habilitar a configuração Permitir que os serviços e recursos do Azure acessem esse servidor não é uma prática de segurança recomendada para cenários de produção. Aplicativos reais devem implementar abordagens mais seguras, como restrições de firewall mais fortes ou configurações de rede virtual.

      Você pode ler mais sobre configurações de segurança de banco de dados nos seguintes recursos:

      • Configurar regras de firewall do Banco de Dados SQL do Azure.
      • Configura uma rede virtual com pontos de extremidade privados.

2. O servidor também deve ter a autenticação do Microsoft Entra habilitada e ter uma conta de administrador do Microsoft Entra atribuída. Para conexões de desenvolvimento local, a conta de administrador do Microsoft Entra deve ser uma conta com a qual você também pode fazer logon no Visual Studio ou na CLI do Azure localmente. Você pode verificar se o seu servidor tem a autenticação do Microsoft Entra habilitada na página ID do Microsoft Entra do seu servidor lógico.

   

3. Se estiver a utilizar uma conta pessoal do Azure, certifique-se de que tem o Microsoft Entra configurado e configurado para o Base de Dados SQL do Azure para atribuir a sua conta como administrador do servidor. Se estiver a usar uma conta corporativa, o Microsoft Entra provavelmente já estará configurado para si.

Criar o projeto

As etapas nesta seção criam uma API Web Mínima do .NET usando a CLI do .NET ou o Visual Studio 2022.

Adicionar o Entity Framework Core ao projeto

Para se ligar ao Base de Dados SQL do Azure usando .NET e Entity Framework Core, adicione os seguintes pacotes NuGet ao seu projeto, utilizando um dos seguintes métodos:

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore.SwaggerUI

Adicionar o código para se conectar ao Banco de Dados SQL do Azure

As bibliotecas do Entity Framework Core dependem das bibliotecas Microsoft.Data.SqlClient e Azure.Identity para implementar conexões sem senha com o Banco de Dados SQL do Azure. A biblioteca Azure.Identity fornece uma classe chamada DefaultAzureCredential que lida com a autenticação sem senha para o Azure.

DefaultAzureCredential suporta vários métodos de autenticação e determina quais usar em tempo de execução. Essa abordagem permite que seu aplicativo use métodos de autenticação diferentes em ambientes diferentes (local versus produção) sem implementar código específico do ambiente. A visão geral da biblioteca de Identidades do Azure explica a ordem e os locais nos quais DefaultAzureCredential procura credenciais.

Conclua as seguintes etapas para se conectar ao Banco de Dados SQL do Azure usando o Entity Framework Core e a classe DefaultAzureCredential subjacente:

1. Adicione uma seção ConnectionStrings ao arquivo appsettings.Development.json para que ele corresponda ao código a seguir. Substitua <server>.database.windows.net pelo nome do servidor de banco de dados sem senha ao qual você deseja se conectar e <database> pelo nome do banco de dados.

   {
       "Logging": {
           "LogLevel": {
               "Default": "Information",
               "Microsoft.AspNetCore": "Warning"
           }
       },
       "ConnectionStrings": {
           "AZURE_SQL_CONNECTIONSTRING": "Data Source=<server>.database.windows.net;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
       }
   }
   

   Observação

   Lembre-se de atualizar os <your database-server-name> e <your-database-name> placeholders na cadeia de conexão do banco de dados. Cadeias de conexão sem senha são seguras para confirmar o controle do código-fonte, pois não contêm segredos, como nomes de usuário, senhas ou chaves de acesso.

   A cadeia de conexão sem senha inclui um valor de configuração de Authentication=Active Directory Default, que permite que o Entity Framework Core use DefaultAzureCredential para se conectar aos serviços do Azure. Quando o aplicativo é executado localmente, ele se autentica com o usuário com o qual você está conectado ao Visual Studio. Depois que o aplicativo é implantado no Azure, o mesmo código descobre e aplica a identidade gerenciada associada ao aplicativo hospedado, que você configura posteriormente.

2. Substitua o conteúdo do arquivo Program.cs com o seguinte código:

   using Microsoft.EntityFrameworkCore;
   
   var builder = WebApplication.CreateBuilder();
   
   builder.Services.AddOpenApi();
   
   var connection = string.Empty;
   if (builder.Environment.IsDevelopment())
   {
       builder.Configuration.AddEnvironmentVariables().AddJsonFile("appsettings.Development.json");
       connection = builder.Configuration.GetConnectionString("AZURE_SQL_CONNECTIONSTRING");
   }
   else
   {
       connection = Environment.GetEnvironmentVariable("AZURE_SQL_CONNECTIONSTRING");
   }
   
   builder.Services.AddDbContext<PersonDbContext>(options =>
       options.UseSqlServer(connection));
   
   var app = builder.Build();
   
   if (app.Environment.IsDevelopment())
   {
       app.MapOpenApi();
       app.UseSwaggerUI(options =>
       {
           options.SwaggerEndpoint("/openapi/v1.json", "v1");
       });
   }
   
   app.MapGet("/", () => "Hello world!");
   
   app.MapGet("/Person", (PersonDbContext context) => context.Person.ToList());
   
   app.MapPost("/Person", (Person person, PersonDbContext context) =>
   {
       context.Add(person);
       context.SaveChanges();
   });
   
   app.Run();
   
   public class Person
   {
       public int Id { get; set; }
       public string FirstName { get; set; }
       public string LastName { get; set; }
   }
   
   public class PersonDbContext(DbContextOptions<PersonDbContext> options) : DbContext(options)
   {
       public DbSet<Person> Person { get; set; }
   }
   

   O código anterior lida com as seguintes etapas:

   • Recupera a cadeia de conexão de banco de dados sem senha do arquivo appsettings.Development.json para desenvolvimento local ou das variáveis de ambiente para cenários de produção hospedados.
   • Registra a classe Entity Framework Core DbContext com o contêiner de injeção de dependência do .NET. Você pode ler mais sobre DbContext na documentação de Introdução do Entity Framework Core.
   • Configura suporte OpenAPI .NET 10.0 com SwaggerUI para fornecer uma interface que pode usar para interagir com os endpoints da aplicação e a base de dados.
   • Adiciona endpoints para recuperar e adicionar entidades na base de dados.
   • Define uma classe Person para representar um único registo na tabela de base de dados Persons, e a classe PersonDbContext que foi registada no contêiner de injeção de dependências do .NET.

Executar as migrações para criar o banco de dados

Para atualizar o esquema da base de dados para corresponder ao seu modelo de dados usando o Entity Framework Core, utilize uma migração. As migrações podem criar e atualizar incrementalmente um esquema de banco de dados para mantê-lo sincronizado com o modelo de dados do seu aplicativo. Para saber mais sobre este padrão, consulte a visão geral das migrações.

Testar o aplicativo localmente

A aplicação está pronta para testar localmente. Certifica-te de que estás ligado ao Visual Studio ou à CLI do Azure com a mesma conta que defines como administrador da tua base de dados.

1. Selecione o botão executar no topo do Visual Studio para lançar o projeto da API.

2. Na página Swagger UI (por exemplo, https://localhost:<port>/swagger), expanda o POST método e selecione Experimentar.

3. Modifique o JSON de exemplo para incluir valores para o nome próprio e o nome da família. Selecione Executar para adicionar um novo registro ao banco de dados. A API retorna uma resposta bem-sucedida.

   

4. Expanda o GET método na página da interface do usuário do Swagger e selecione Experimentar. Selecione Executare a pessoa que você acabou de criar será retornada.

Implantar no Serviço de Aplicações do Azure

A aplicação está pronta para ser implementada no Azure. O Visual Studio pode criar um Serviço de Aplicativo do Azure e implantar seu aplicativo em um único fluxo de trabalho.

1. Certifique-se de que a aplicação está parada e que se compila com sucesso.

2. Na janela Explorador de Soluções do Visual Studio, clique com o botão direito no nó do projeto de nível superior e selecione Publicar.

3. Na caixa de diálogo de publicação, selecione Azure como destino de implantação e, em seguida, selecione Avançar.

4. Para o destino específico, selecione Serviço de Aplicativo do Azure (Windows)e, em seguida, selecione Avançar.

5. Selecione o ícone de + verde para criar um novo Serviço de Aplicativo para implantar e insira os seguintes valores:

   • Nome: Deixe o valor padrão.
   • Nome da subscrição: Selecione a subscrição para implementar.
   • Grupo de recursos: Selecione Novo e crie um novo grupo de recursos chamado msdocs-dotnet-sql.
   • Plano de Hospedagem: Selecione Novo para abrir a caixa de diálogo do plano de hospedagem. Deixe os valores padrão e selecione OK.
   • Selecione Criar para fechar a caixa de diálogo original. O Visual Studio cria o recurso Serviço de Aplicativo no Azure.

   

6. Depois de criar o recurso, certifique-se de que o seleciona na lista de serviços de aplicação e depois selecione Próximo.

7. Na etapa Gerenciamento de API, marque a caixa de seleção Ignorar esta etapa na parte inferior e, em seguida, selecione Concluir.

8. Selecione Publicar no canto superior direito do resumo do perfil de publicação para implantar o aplicativo no Azure.

Quando a implantação terminar, o Visual Studio inicia o navegador para exibir o aplicativo hospedado. Vês a mensagem Hello world do endpoint predefinido. No entanto, nesta altura, os endpoints do banco de dados não funcionam corretamente no Azure. Você ainda precisa configurar a conexão segura entre o Serviço de Aplicativo e o banco de dados SQL para recuperar seus dados.

Conectar o Serviço de Aplicativo ao Banco de Dados SQL do Azure

Para ligar a instância do App Service ao Base de Dados SQL do Azure, complete os seguintes passos:

1. Crie uma identidade gerenciada para o Serviço de Aplicativo. A Microsoft.Data.SqlClient biblioteca incluída em seu aplicativo descobre automaticamente a identidade gerenciada, assim como descobriu seu usuário local do Visual Studio.

2. Crie um usuário do banco de dados SQL e associe-o à identidade gerenciada do Serviço de Aplicativo.

3. Atribua funções SQL ao usuário do banco de dados que permitam leitura, gravação e potencialmente outras permissões.

Pode usar várias ferramentas para implementar estes passos:

Testar o aplicativo implantado

Navegue até a URL do aplicativo para testar se a conexão com o Banco de Dados SQL do Azure está funcionando. Você pode localizar a URL do seu aplicativo na página de visão geral do Serviço de Aplicativo. Anexe o caminho /person ao final da URL para navegar até o mesmo ponto de extremidade testado localmente.

A pessoa que você criou localmente deve ser exibida no navegador. Parabéns, seu aplicativo agora está conectado ao Banco de Dados SQL do Azure em ambientes locais e hospedados.

Limpar os recursos

Quando terminar de trabalhar com o Banco de Dados SQL do Azure, exclua o recurso para evitar custos não intencionais.

az sql db delete --name <database-name> --resource-group <resource-group-name> --server <logical-server-name>

Conteúdo relacionado

• Tutorial: Proteger um banco de dados no Banco de Dados SQL do Azure
• Autorizar o acesso à base de dados ao Base de Dados SQL do Azure
• Uma visão geral dos recursos de segurança do Banco de Dados SQL do Azure e da Instância Gerenciada SQL
• Plano de Ação para abordar requisitos de segurança comuns com a Base de Dados SQL do Azure e a Instância Gerida SQL do Azure