Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Microsoft.Data.SqlClient é o provedor de dados .NET com suporte para SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure, Azure Synapse Analytics, banco de dados SQL no Microsoft Fabric e Data Warehouse no Microsoft Fabric. O driver é distribuído como pacotes NuGet independentemente do runtime do .NET.
Escolha um lançamento
Use uma versão de Disponibilidade Geral (GA) suportada para aplicações de produção.
| Link da versão | Nível de suporte | Escolha-o quando |
|---|---|---|
| 7.0 | Suporte Padrão por Período (STS) | Você precisa de recursos mais recentes do driver e pode atualizar na cadência regular de versões. |
| 6.1 | LTS (suporte de longo prazo) | Você prefere um período de suporte mais longo e não precisa de recursos introduzidos na 7.0. |
Para versões atuais de patch, datas de suporte, frameworks de destino e compatibilidade com banco de dados, veja ciclo de vida do suporte ao driver SqlClient.
Instale o pacote principal
Execute o seguinte comando a partir do diretório que contém seu arquivo de 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>
Restaure dependências e construa o projeto:
dotnet restore
dotnet build
Importar o namespace do driver em C#:
using Microsoft.Data.SqlClient;
Para novas aplicações, não faça referência ao pacote ou namespace antigo System.Data.SqlClient . Para atualizar um aplicativo existente, veja Migrar de System.Data.SqlClient para Microsoft. Data.SqlClient.
Instalar com Visual Studio
- No Gerenciador de Soluções, clique com o botão direito no projeto e selecione Gerenciar Pacotes NuGet.
- Na aba Navegar, procure por
Microsoft.Data.SqlClient. - Selecione o pacote pertencente à Microsoft.
- Selecione uma versão estável suportada e então selecione Instalar.
Para mais informações, veja Instalar e gerenciar pacotes no Visual Studio.
Adicionar pacotes opcionais
Instale pacotes opcionais apenas quando seu aplicativo usar o recurso relacionado.
| Package | Adicione-o quando |
|---|---|
Microsoft.Data.SqlClient.Extensions.Azure |
Microsoft. Data.SqlClient 7.0 ou posterior utiliza um modo de autenticação Microsoft Entra fornecido por drivers, como Active Directory Default, Active Directory Interactive, ou Active Directory Managed Identity. |
Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider |
Always Encrypted armazena chaves mestras de coluna no Azure Key Vault. |
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 core 7.0 não inclui mais dependências do Azure Identity. A partir da versão 7.0.2, o driver principal e os pacotes companheiros usam versões alinhadas. Consulte a mesma versão de Microsoft.Data.SqlClient e Microsoft.Data.SqlClient.Extensions.Azure. Aplicativos que não usam autenticação Microsoft Entra fornecida pelo driver não precisam do pacote de extensão do Azure. Para configuração de autenticação, veja autenticação Microsoft Entra.
Atualizar o driver
Antes de atualizar:
Leia What's new in Microsoft.Data.SqlClient e as notas de lançamento upstream de cada versão abrangida pela atualização.
Verifique as referências diretas e transitivas dos pacotes da aplicação.
dotnet list package --include-transitiveAtualize a referência do pacote.
dotnet add package Microsoft.Data.SqlClient --version <version>Restaure, construa e execute os testes da aplicação.
Teste o estabelecimento da conexão, a autenticação, a validação de certificados, o pool de conexões, as conversões de tipos de dados, as transações e o comportamento de novas tentativas em cada banco de dados de destino suportado.
Lançamentos principais e de patches podem exigir mudanças na aplicação. Por exemplo, a versão 4.0 habilitava a criptografia por padrão, a versão 5.0 mudava SqlConnectionStringBuilder.Encrypt de bool para SqlConnectionEncryptOption, e a versão 7.0 transferia a autenticação Microsoft Entra fornecida pelo driver para um pacote separado.
A partir da versão 7.0.2, as versões de assembly de Microsoft.Data.SqlClient.Extensions.Azure, Microsoft.Data.SqlClient.Internal.Logging e 1.0.0.0 mudaram de 7.0.0.0 para Microsoft.Data.SqlClient.Extensions.Abstractions. É preciso recompilar aplicativos do .NET Framework com base nos pacotes alinhados ou adicionar redirecionamentos de associação. Os aplicativos no .NET atual não são afetados por essa mudança na identidade do assembly.
Entenda os frameworks de destino
Microsoft. Data.SqlClient 7.0 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. Um aplicativo executável deve ter como destino um runtime com suporte do .NET ou do .NET Framework. O destino para o .NET Standard de uma biblioteca não significa que todo runtime que a consome tem suporte.
O pacote restaura suas dependências gerenciadas e nativas por meio do NuGet. Não copie assemblies individuais de drivers ou bibliotecas nativas da Interface de Rede SQL (SNI) entre aplicações.
Preparar para a implantação
Publique para o mesmo sistema operacional e a mesma arquitetura usados em produção. Para uma implantação dependente do framework:
dotnet publish --configuration ReleasePara uma implantação específica do runtime:
dotnet publish --configuration Release --runtime <runtime-identifier>Implante o resultado completo da publicação. Não selecione apenas
Microsoft.Data.SqlClient.dll.Confirme que o alvo possui o runtime .NET exigido, a menos que você publique uma aplicação autônoma.
Teste a saída publicada no sistema operacional e na arquitetura alvo.
Teste todos os modos de autenticação usados em produção. Autenticação integrada, Kerberos, certificados, identidade gerenciada e acesso ao Azure Key Vault dependem do ambiente de implantação.
Escaneie o gráfico de dependência resolvido em busca de vulnerabilidades conhecidas e atualize as linhas de pacote suportadas quando as correções estiverem disponíveis.
O modo invariável de globalização não é suportado. Para qualificações atuais da plataforma, veja Sistemas operacionais suportados.
Instalação offline de pacotes
Baixe o pacote e suas dependências de NuGet.org, copie para um código-fonte interno e restaure a partir dessa fonte. Para compilações offline reproduzíveis, fixe as versões dos pacotes e preserve o conjunto completo de dependências.