Zainstaluj, aktualizuj i wdrażaj Microsoft. Data.SqlClient

Microsoft.Data.SqlClient jest obsługiwanym dostawcą danych .NET dla SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, bazy danych SQL w Microsoft Fabric oraz Magazynu danych w Microsoft Fabric. Sterownik jest dostarczany jako pakiety NuGet niezależnie od środowiska uruchomieniowego .NET.

Wybierz wydanie

Używaj wspieranej wersji General Availability (GA) dla aplikacji produkcyjnych.

Informacje o bieżących wersjach poprawek, datach wsparcia, platformach docelowych i zgodności z bazami danych można znaleźć w artykule Cykl wsparcia sterownika SqlClient.

Zainstaluj pakiet podstawowy

Uruchom następujące polecenie z katalogu zawierającego plik projektu:

dotnet add package Microsoft.Data.SqlClient

Polecenie wybiera najnowszą stabilną wersję kompatybilną z projektem. Aby przypisać wersję na potrzeby powtarzalnych kompilacji, określ wersję:

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

Przywróć zależności i zbuduj projekt:

dotnet restore
dotnet build

Importuj przestrzeń nazw sterownika w C#:

using Microsoft.Data.SqlClient;

W przypadku nowych aplikacji nie odwołuj się do starszego System.Data.SqlClient pakietu ani przestrzeni nazw. Aby zaktualizować istniejącą aplikację, zobacz Migracja z System.Data.SqlClient do Microsoft. Data.SqlClient.

Instalowanie za pomocą programu Visual Studio

1. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy na projekt i wybierz Manage NuGet Packages.
2. Na zakładce Przeglądaj wyszukaj .Microsoft.Data.SqlClient
3. Wybierz pakiet należący do Microsoftu.
4. Wybierz obsługiwaną stabilną wersję, a następnie wybierz Zainstaluj.

Więcej informacji można znaleźć w sekcji Instaluj i zarządzaj pakietami w Visual Studio.

Dodaj opcjonalne pakiety

Instaluj opcjonalne pakiety tylko wtedy, gdy Twoja aplikacja korzysta z powiązanej funkcji.

Dla uwierzytelniania Microsoft Entra z SqlClient 7.0 lub nowszym, wykonaj:

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

Podstawowy pakiet 7.0 nie zawiera już zależności biblioteki Azure Identity. Od wersji 7.0.2 główny sterownik i pakiety towarzyszące używają spójnych numerów wersji. Odwołuj się do tej samej wersji Microsoft.Data.SqlClient i Microsoft.Data.SqlClient.Extensions.Azure. Aplikacje, które nie korzystają z uwierzytelniania Microsoft Entra za pomocą sterowników, nie potrzebują pakietu rozszerzenia Azure. Aby uzyskać konfigurację uwierzytelniania, zobacz Microsoft Entra authentication.

Aktualizowanie sterownika

Przed aktualizacją:

1. Przeczytaj Co nowego w Microsoft.Data.SqlClient oraz oryginalne informacje o wydaniu dla każdej wersji pominiętej w ramach aktualizacji.

2. Sprawdź bezpośrednie i przechodnie odniesienia pakietów aplikacji.

   dotnet list package --include-transitive
   

3. Zaktualizuj referencję pakietu.

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

4. Przywróć, zbuduj i uruchom testy aplikacji.

5. Testuj nawiązywanie połączeń, uwierzytelnianie, walidację certyfikatów, pulowanie połączeń, konwersje typów danych, transakcje oraz zachowanie powtórne wobec każdego obsługiwanego celu bazy danych.

Główne i patchowe wydania mogą wymagać zmian aplikacji. Na przykład wersja 4.0 domyślnie włączała szyfrowanie, wersja 5.0 zmieniła SqlConnectionStringBuilder.Encrypt z bool na SqlConnectionEncryptOption, a wersja 7.0 przeniosła uwierzytelnianie Microsoft Entra dostarczane przez sterownik do osobnego pakietu.

Począwszy od wersji 7.0.2, wersje zestawu Microsoft.Data.SqlClient.Extensions.Azure, Microsoft.Data.SqlClient.Extensions.Abstractions i Microsoft.Data.SqlClient.Internal.Logging zmieniono z 1.0.0.0 na 7.0.0.0. Aplikacje .NET Framework muszą zostać ponownie skompilowane względem uzgodnionych pakietów lub wymagać dodania przekierowań powiązań. Zmiana tożsamości zestawu nie ma wpływu na aplikacje działające w bieżącym środowisku .NET.

Zrozum ramy docelowe

Microsoft. Data.SqlClient 7.0 obsługuje aplikacje na:

• .NET Framework 4.6.2 lub nowszy na Windows.
• .NET 8 lub nowszy w obsługiwanych wersjach systemów Windows, Linux i macOS.

Pakiet NuGet zawiera również składnik zgodności ze standardem .NET Standard 2.0 dla bibliotek. Aplikacja wykonywalna musi być przeznaczona dla obsługiwanego środowiska uruchomieniowego .NET lub .NET Framework. To, że biblioteka jest przeznaczona dla platformy .NET Standard, nie oznacza, że obsługiwane jest każde środowisko uruchomieniowe, które z niej korzysta.

Pakiet przywraca swoje zarządzane i natywne zależności za pomocą NuGet. Nie kopiuj pojedynczych zestawów sterowników ani natywnych bibliotek SQL Network Interface (SNI) między aplikacjami.

Przygotowanie do wdrożenia

1. Opublikuj dla tego samego systemu operacyjnego i architektury używanych w środowisku produkcyjnym. Dla wdrożenia zależnego od środowiska uruchomieniowego:

   dotnet publish --configuration Release
   

   Dla wdrożenia dla konkretnego środowiska uruchomieniowego:

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

2. Wdroż pełny wynik publikacji. Nie wybieraj tylko Microsoft.Data.SqlClient.dll.

3. Upewnij się, że środowisko docelowe ma wymagane środowisko uruchomieniowe .NET, chyba że publikujesz aplikację niezależną.

4. Przetestuj opublikowane wyniki na docelowym systemie operacyjnym i architekturze.

5. Testuj każdy tryb uwierzytelniania używany w produkcji. Zintegrowana uwierzytelnianie, Kerberos, certyfikaty, tożsamość zarządzana oraz dostęp do Azure Key Vault zależą od środowiska wdrożenia.

6. Przeskanuj graf zależności rozwiązanych pod kątem znanych luk i aktualizuj obsługiwane linie pakietów, gdy pojawią się poprawki.

Tryb niezmienny globalizacji nie jest obsługiwany. Aktualne kwalifikacje dotyczące platform można znaleźć w sekcji Obsługiwane systemy operacyjne.

Instalacja pakietów offline

Pobierz pakiet i jego zależności z NuGet.org, skopiuj je do wewnętrznego kodu kodowego pakietu i przywróć go z tego źródła. Dla powtarzalnych kompilacji offline należy pinować wersje pakietów i zachować pełny zestaw zależności.

Treści powiązane

• Zacznij od sterownika SqlClient
• Co nowego w Microsoft. Data.SqlClient
• Cykl życia wsparcia sterownika SqlClient
• Wersje Microsoft.Data.SqlClient