Instalar, atualizar e implementar a Microsoft. Data.SqlClient

Microsoft.Data.SqlClient é o fornecedor de dados do .NET suportado para SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance, Azure Synapse Analytics, base de dados SQL na Microsoft Fabric e Warehouse na Microsoft Fabric. O controlador é disponibilizado como pacotes NuGet, de forma independente do ambiente de execução .NET.

Escolha uma libertação

Use uma versão suportada de Disponibilidade Geral (GA) para aplicações de produção. A versão mais recente do GA é Microsoft.Data.SqlClient 7.1.0.

Para versões atuais de patch, datas de suporte, frameworks de destino e compatibilidade com bases de dados, consulte ciclo de vida do suporte ao driver SqlClient.

Instale o pacote core

Execute o seguinte comando a partir do diretório que contém o ficheiro do seu projeto:

dotnet add package Microsoft.Data.SqlClient

O comando seleciona a versão estável mais recente compatível com o projeto. Para fixar uma versão para compilações reproduzíveis, especifique a versão:

dotnet add package Microsoft.Data.SqlClient --version <version>

Restaurar dependências e construir o projeto:

dotnet restore
dotnet build

Importar o namespace do driver em C#:

using Microsoft.Data.SqlClient;

Para aplicações novas, não faça referência ao pacote ou namespace antigo System.Data.SqlClient . Para atualizar uma aplicação existente, consulte Migrar de System.Data.SqlClient para Microsoft. Data.SqlClient.

Instalar com Visual Studio

1. No Explorador de Soluções, clique com o botão direito no projeto e selecione Gerir Pacotes NuGet.
2. No separador Navegar , procure por Microsoft.Data.SqlClient.
3. Selecione o pacote pertencente à Microsoft.
4. Selecione uma versão estável suportada e depois selecione Instalar.

Para mais informações, consulte Instalar e gerir pacotes no Visual Studio.

Adicionar pacotes opcionais

Instale pacotes opcionais apenas quando a sua aplicação usar a funcionalidade relacionada.

Para autenticação Microsoft Entra com SqlClient 7.0 ou posterior, execute:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>

O pacote principal 7.0 já não inclui dependências do Azure Identity. A partir da versão 7.0.2, o driver principal e os pacotes companheiros utilizam versões alinhadas. Referenciar a mesma versão de Microsoft.Data.SqlClient e Microsoft.Data.SqlClient.Extensions.Azure. Aplicações que não usam autenticação Microsoft Entra fornecida por drivers não precisam do pacote de extensão Azure. Para configuração de autenticação, consulte autenticação Microsoft Entra.

Atualizar o controlador

Antes de atualizar:

1. Leia Novidades no Microsoft.Data.SqlClient e as notas de versão originais de cada versão abrangida pela atualização.

2. Verifique as referências diretas e transitivas dos pacotes da aplicação.

   dotnet list package --include-transitive
   

3. Atualize a referência da embalagem.

   dotnet add package Microsoft.Data.SqlClient --version <version>
   

4. Restaurar, construir e executar os testes da aplicação.

5. Testar o estabelecimento de ligações, a autenticação, a validação de certificados, o agrupamento de ligações, as conversões de tipos de dados, as transações e o comportamento de repetição para cada base de dados de destino suportada.

Lançamentos principais e de patches podem exigir alterações na aplicação. Por exemplo, a versão 4.0 permitia a encriptação por defeito, a versão 5.0 mudou SqlConnectionStringBuilder.Encrypt de bool para SqlConnectionEncryptOption, e a versão 7.0 transferiu a autenticação Microsoft Entra fornecida pelo driver para um pacote separado.

A partir da versão 7.0.2, as versões de assemblagem de Microsoft.Data.SqlClient.Extensions.Azure, Microsoft.Data.SqlClient.Internal.Logging e 1.0.0.0 foram alteradas de 7.0.0.0 para Microsoft.Data.SqlClient.Extensions.Abstractions. As aplicações do .NET Framework têm de ser recompiladas com base nos pacotes alinhados ou adicionar redirecionamentos de associação. As aplicações na versão atual do .NET não são afetadas por esta alteração da identidade do assembly.

Compreender as estruturas de destino

Microsoft. Data.SqlClient 7.1 suporta aplicações em:

• .NET Framework 4.6.2 ou posterior no Windows.
• .NET 8 ou versões posteriores suportavam versões para Windows, Linux e macOS.

O pacote NuGet também contém um ativo de compatibilidade .NET Standard 2.0 para bibliotecas. Uma aplicação executável tem de se destinar a um runtime suportado do .NET ou do .NET Framework. O facto de uma biblioteca ter como destino o .NET Standard não significa que todos os runtimes que a consomem sejam suportados.

O pacote restaura as suas dependências geridas e nativas através do NuGet. Não copie assemblies individuais de drivers ou bibliotecas nativas da Interface de Rede SQL (SNI) entre aplicações.

Prepare-se para a implantação

1. Publique para o mesmo sistema operativo e arquitetura utilizados em produção. Para uma implementação dependente do framework:

   dotnet publish --configuration Release
   

   Para uma implementação específica do ambiente de execução:

   dotnet publish --configuration Release --runtime <runtime-identifier>
   

2. Implemente o resultado completo de publicação. Não selecione apenas Microsoft.Data.SqlClient.dll.

3. Confirme que o alvo tem o tempo de execução .NET necessário, a menos que publique uma aplicação autónoma.

4. Teste o resultado publicado no sistema operativo e na arquitetura de destino.

5. Teste todos os modos de autenticação usados em produção. Autenticação integrada, Kerberos, certificados, identidade gerida e acesso ao Azure Key Vault dependem do ambiente de implementação.

6. Analise o grafo de dependências resolvidas à procura de vulnerabilidades conhecidas e atualize as linhas de pacotes suportadas quando houver correções disponíveis.

O modo invariante à globalização não é suportado. Para qualificações atuais da plataforma, veja Sistemas operativos suportados.

Instalação de pacotes offline

Descarregue o pacote e as suas dependências de NuGet.org, copie-os para um código-fonte interno e restaure a partir dessa fonte. Para compilações offline reproduzíveis, fixar as versões dos pacotes e preservar o conjunto completo de dependências.

Conteúdo relacionado

• Comece a usar o driver SqlClient
• Novidades na Microsoft. Data.SqlClient
• Ciclo de vida do suporte de controladores do SqlClient
• Versões do Microsoft.Data.SqlClient