Conectar-se e consultar o Azure Banco de Dados SQL do Azure usando o .NET e a biblioteca Microsoft.Data.SqlClient

  • Artigo

Aplica-se a:Banco de Dados SQL do Azure

Este guia de início rápido descreve como conectar um aplicativo a um banco de dados no Banco de Dados SQL do Azure e executar consultas usando o .NET e a biblioteca Microsoft.Data.SqlClient. Este guia de início rápido segue a abordagem sem senha recomendada para se conectar ao banco de dados. Você pode saber mais sobre conexões sem senha no hub sem senha.

Pré-requisitos

Configurar o banco de dados

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

  1. Para conexões de desenvolvimento local, verifique se o servidor lógico está configurado para permitir que o endereço IP do computador local e outros serviços do Azure se conectem:

    • Navegue até a página de Rede do servidor.

    • Clique no botão de opção Redes selecionadas para mostrar opções de configuração adicionais.

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

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

      A screenshot showing how to configure firewall rules.

      Aviso

      Habilitar a configuração Permitir que serviços e recursos do Azure acessem esse servidor não é uma prática de segurança recomendada para cenários de produção. Os 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:

  2. O servidor também deve ter a autenticação do Microsoft Entra habilitada e ter uma conta do administrador do Microsoft Entra atribuída. Para conexões de desenvolvimento local, a conta do 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 servidor tem a autenticação do Microsoft Entra habilitada na página Microsoft Entra ID do servidor lógico.

    A screenshot showing how to enable Microsoft Entra authentication.

  3. Se você estiver usando uma conta pessoal do Azure, verifique se tem a instalação e configuração do Microsoft Entra para o Banco de Dados SQL do Azure para atribuir sua conta à administração do servidor. Se você estiver usando uma conta corporativa, o Microsoft Entra ID provavelmente já estará configurado.

Criar o projeto

Para as próximas etapas, crie uma API Web Mínima .NET usando a CLI do .NET ou o Visual Studio 2022.

  1. No menu do Visual Studio, navegue até Arquivo>Novo>Projeto...

  2. Na janela de diálogo, insira ASP.NET na caixa de pesquisa do modelo de projeto e selecione o resultado da API Web ASP.NET Core. Escolha Avançar na parte inferior do diálogo.

  3. Para o Nome do Projeto, insira DotNetSQL. Deixe os outros campos com os valores padrão e selecione Avançar.

  4. Para o Framework, selecione .NET 7.0 e desmarque Usar controladores (desmarque para usar APIs mínimas). Este início rápido usa um modelo de API mínima para simplificar a criação e a configuração do ponto de extremidade.

  5. Escolha Criar. O novo projeto será aberto no ambiente do Visual Studio.

Adicionar a biblioteca Microsoft.Data.SqlClient

Para conectar-se ao Banco de Dados SQL do Azure usando .NET, instale Microsoft.Data.SqlClient. Esse pacote atua como um provedor de dados para se conectar a bancos de dados, executar comandos e recuperar resultados.

Observação

Instale Microsoft.Data.SqlClient, e não System.Data.SqlClient. Microsoft.Data.SqlClient é uma versão mais recente da biblioteca de clientes SQL que fornece recursos adicionais.

  1. Na janela Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências do projeto e selecione Gerenciar Pacotes NuGet.

  2. Na janela resultante, pesquise por SqlClient. Localize o resultado Microsoft.Data.SqlClient e selecione Instalar.

Configurar a cadeia de conexão

Para desenvolvimento local com conexões sem senha com o Banco de Dados SQL do Azure, adicione a seção ConnectionStrings a seguir ao arquivo appsettings.json. Substitua os espaços reservados <database-server-name> e <database-name> pelos seus próprios valores.

"ConnectionStrings": {
    "AZURE_SQL_CONNECTIONSTRING": "Server=tcp:<database-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Authentication=\"Active Directory Default\";"
}

A cadeia de conexão sem senha define um valor de configuração de Authentication="Active Directory Default", que instrui a biblioteca Microsoft.Data.SqlClient a se conectar ao Banco de Dados SQL do Azure usando uma classe chamada DefaultAzureCredential. O DefaultAzureCredential permite conexões sem senha com os serviços do Azure e é fornecido pela biblioteca de identidade do Azure da qual a biblioteca de clientes SQL depende. O DefaultAzureCredential dá suporte a vários métodos de autenticação e determina qual usar no runtime para diferentes ambientes.

Por exemplo, quando o aplicativo é executado localmente, DefaultAzureCredential faz a autenticação por meio do usuário com o qual você está conectado ao Visual Studio ou outras ferramentas locais, como a CLI do Azure. Depois que o aplicativo for implantado no Azure, o mesmo código descobrirá e aplicará a identidade gerenciada associada ao aplicativo hospedado, que você configurará posteriormente. A Visão geral da biblioteca de Identidade do Azure explica a ordem e os locais nos quais o DefaultAzureCredential procura por credenciais.

Observação

As 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.

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

Substitua o conteúdo do arquivo Program.cs pelo código a seguir, que executa as seguintes etapas importantes:

  • Recupera a cadeia de conexão sem senha de appsettings.json
  • Cria uma tabela Persons no banco de dados durante a inicialização (somente para cenários de teste)
  • Cria um ponto de extremidade HTTP GET para recuperar todos os registros armazenados na tabela Persons
  • Criar um ponto de extremidade HTTP POST para adicionar novos registros à tabela Persons
using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// For production scenarios, consider keeping Swagger configurations behind the environment check
// if (app.Environment.IsDevelopment())
// {
    app.UseSwagger();
    app.UseSwaggerUI();
// }

app.UseHttpsRedirection();

string connectionString = app.Configuration.GetConnectionString("AZURE_SQL_CONNECTIONSTRING")!;

try
{
    // Table would be created ahead of time in production
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "CREATE TABLE Persons (ID int NOT NULL PRIMARY KEY IDENTITY, FirstName varchar(255), LastName varchar(255));",
        conn);
    using SqlDataReader reader = command.ExecuteReader();
}
catch (Exception e)
{
    // Table may already exist
    Console.WriteLine(e.Message);
}

app.MapGet("/Person", () => {
    var rows = new List<string>();

    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand("SELECT * FROM Persons", conn);
    using SqlDataReader reader = command.ExecuteReader();

    if (reader.HasRows)
    {
        while (reader.Read())
        {
            rows.Add($"{reader.GetInt32(0)}, {reader.GetString(1)}, {reader.GetString(2)}");
        }
    }

    return rows;
})
.WithName("GetPersons")
.WithOpenApi();

app.MapPost("/Person", (Person person) => {
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "INSERT INTO Persons (firstName, lastName) VALUES (@firstName, @lastName)",
        conn);

    command.Parameters.Clear();
    command.Parameters.AddWithValue("@firstName", person.FirstName);
    command.Parameters.AddWithValue("@lastName", person.LastName);

    using SqlDataReader reader = command.ExecuteReader();
})
.WithName("CreatePerson")
.WithOpenApi();

app.Run();

Por fim, adicione a classe Person à parte inferior do arquivo Program.cs. Essa classe representa um único registro na tabela Persons do banco de dados.

public class Person
{
    public required string FirstName { get; set; }
    public required string LastName { get; set; }
}

Executar e testar o aplicativo localmente

O aplicativo está pronto para ser testado localmente. Verifique se você está conectado ao Visual Studio ou à CLI do Azure com a mesma conta definida como o administrador do banco de dados.

  1. Pressione o botão Executar na parte superior do Visual Studio para iniciar o projeto de API.

  2. Na página interface do usuário do Swagger, expanda o método POST e selecione Experimentar.

  3. Modifique o JSON de amostra para incluir valores para o nome e sobrenome. Selecione Executar para adicionar um novo registro ao banco de dados. A API retorna uma resposta bem-sucedida.

    A screenshot showing how to test the API.

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

Implantar no Serviço de Aplicativo do Azure

O aplicativo está pronto para ser implantado 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. Verifique se o aplicativo foi interrompido e compilado com êxito.

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

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

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

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

    • Nome: deixe o valor padrão.

    • Nome da assinatura: selecione a assinatura na qual implantar.

    • Grupo de recursos: selecione Novo e crie um grupo de recursos chamado msdocs-dotnet-sql.

    • Plano de Hospedagem: selecione Novo para abrir a caixa de diálogo do plano de hospedagem. Mantenha 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.

      A screenshot showing how to deploy with Visual Studio.

  6. Após o recurso ser criado, verifique se ele está selecionado na lista de serviços de aplicativos e selecione Avançar.

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

  8. Na etapa Concluir, selecione Fechar se a caixa de diálogo não fechar automaticamente.

  9. Selecione Publicar na parte superior direita do resumo do perfil de publicação para implantar o aplicativo no Azure.

Quando a implantação é concluída, o Visual Studio inicia o navegador para exibir o aplicativo hospedado. Mas nesse ponto, o aplicativo não funciona 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

As etapas a seguir são necessárias para criar uma conexão sem senha entre a instância do Serviço de Aplicativo e o Banco de Dados SQL do Azure:

  1. Crie uma identidade gerenciada para o Serviço de Aplicativo. A biblioteca Microsoft.Data.SqlClient incluída em seu aplicativo descobrirá automaticamente a identidade gerenciada, assim como descobriu o 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 permitem leitura, gravação e, potencialmente, outras permissões.

Há várias ferramentas disponíveis para implementar estas etapas:

O Conector de Serviço é uma ferramenta que simplifica as conexões autenticadas entre diferentes serviços no Azure. Atualmente, o Conector de Serviço dá suporte à conexão de um Serviço de Aplicativo a um banco de dados SQL por meio da CLI do Azure usando o comando az webapp connection create sql. Este único comando conclui as três etapas mencionadas acima para você.

az webapp connection create sql \
    -g <app-service-resource-group> \
    -n <app-service-name> \
    --tg <database-server-resource-group> \
    --server <database-server-name> \
    --database <database-name> \
    --system-identity

Você pode verificar as alterações feitas pelo Conector de Serviço nas configurações do Serviço de Aplicativo.

  1. Navegue até a página Identidade do seu Serviço de Aplicativo. Na guia Sistema atribuído, o Status deve ser definido como Ativado. Esse valor significa que uma identidade gerenciada atribuída pelo sistema foi habilitada para seu aplicativo.

  2. Navegue até a página Configuração do seu Serviço de Aplicativo. Na guia Cadeias de conexão, você deverá ver uma cadeia de conexão chamada AZURE_SQL_CONNECTIONSTRING. Selecione o texto Clique para mostrar o valor para exibir a cadeia de conexão sem senha gerada. O nome dessa cadeia de conexão coincide com o que você configurou em seu aplicativo. Portanto, ele será descoberto automaticamente ao ser executado no Azure.

Importante

Embora essa solução forneça uma abordagem simples para começar, ela não é uma melhor prática para ambientes de produção. Nesses cenários, o aplicativo não deve executar todas as operações usando uma única identidade elevada. Você deve tentar implementar o princípio de privilégios mínimos configurando várias identidades com permissões específicas para tarefas específicas.

Você pode ler mais sobre como configurar funções de banco de dados e segurança nos seguintes recursos:

Testar o aplicativo implantado

  1. Selecione o botão Procurar na parte superior da página de visão geral do Serviço de Aplicativo para iniciar a URL raiz do aplicativo.

  2. Acrescente o caminho /swagger/index.html à URL para carregar a mesma página de teste do Swagger que você usou localmente.

  3. Execute solicitações GET e POST de teste para verificar se os pontos de extremidade funcionam conforme o esperado.

Dica

Se você receber um erro de servidor interno 500 durante o teste, isso poderá ser resultante das configurações de rede do banco de dados. Verifique se o servidor lógico foi configurado com as configurações descritas na seção Configurar o banco de dados.

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.

  1. Na barra de pesquisa portal do Azure, pesquise SQL do Azure e selecione o resultado correspondente.

  2. Localize e selecione seu banco de dados na lista de bancos de dados.

  3. Na página Visão geral do Banco de Dados SQL do Azure, selecione Excluir.

  4. Na página Tem certeza de que deseja excluir... que é aberta, digite o nome do banco de dados para confirmar e selecione Excluir.