LocalDB i lokalny rozwój z SqlClient

Pobieranie ADO.NET

SQL Server Express LocalDB to lekki silnik SQL Server do lokalnego rozwoju na Windows. Działa pod twoją tożsamością użytkownika Windows i uruchamia się na żądanie. LocalDB nie jest zdalną usługą bazy danych i nie działa na Linuksie ani macOS.

Do rozwoju wieloplatformowego używaj wspieranego kontenera SQL Server lub zdalnego endpointu SQL. Instalacja pakietu Microsoft.Data.SqlClient NuGet instaluje sterownik klienta, a nie LocalDB.

Instalowanie bazy danych LocalDB

Zainstaluj LocalDB za pomocą instalatora SQL Server Express lub Instalatora Visual Studio. W Visual Studio wybierz odpowiednie obciążenie do tworzenia danych lub pojedynczy komponent SQL Server Express LocalDB. Zobacz instalację SQL Server Express LocalDB, aby poznać aktualne pobrania i opcje instalatora.

Instalacja LocalDB dostarcza silnik, SQLUserInstance.dll, oraz SqlLocalDB.exe narzędzie zarządzania. Jeśli SqlLocalDB nie znajduje się na PATH, uruchom go z katalogu zainstalowanych narzędzi SQL Server.

Wypisz zainstalowane wersje i instancje:

SqlLocalDB versions
SqlLocalDB info

Połącz z automatycznym wystąpieniem

Automatyczna instancja nosi nazwę MSSQLLocalDB i należy do bieżącego użytkownika systemu Windows. Używaj zintegrowanej autentykacji Windows. LocalDB nie obsługuje uwierzytelniania Microsoft Entra.

Dla aplikacji konsolowej .NET z zainstalowanym elementem Microsoft.Data.SqlClient:

using Microsoft.Data.SqlClient;

string connectionString =
    @"Server=(localdb)\MSSQLLocalDB;Database=master;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;";

using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();
using var command = new SqlCommand("SELECT DB_NAME();", connection);
Console.WriteLine(await command.ExecuteScalarAsync());

Zapytanie wyświetla master. Pierwsze połączenie może trwać dłużej, ponieważ LocalDB tworzy lub uruchamia instancję. Jeśli uruchomienie przekroczy limit łączenia, sprawdź status instancji, poczekaj na zakończenie uruchomienia i spróbuj ponownie.

Ten przykład umożliwia użycie lokalnego certyfikatu deweloperskiego z TrustServerCertificate=true. Zachowaj ten wyjątek ograniczonym do lokalnego rozwoju. Dla zdalnego endpointu SQL użyj weryfikowalnego certyfikatu oraz TrustServerCertificate=false; zobacz Szyfrowanie i walidacja certyfikatów.

Ukośniki wsteczne w parametrach połączenia

Wartość ciągu łączności zawiera jeden ukośnik wsteczny pomiędzy (localdb) a nazwą instancji. Escaping zależy od tego, gdzie wpiszesz wartość:

Nie kopiuj podwójnych ukośników C# do zwykłego tekstu parametry połączenia.

Instancje nazwane i współdzielone

Używaj instancji o nazwie, gdy chcesz mieć osobną lokalną instancję silnika dla aplikacji. Stwórz go przed połączeniem:

SqlLocalDB create SqlClientDev
SqlLocalDB start SqlClientDev
SqlLocalDB info SqlClientDev

Połącz się za pomocą tych parametrów połączenia w postaci zwykłego tekstu:

Server=(localdb)\SqlClientDev;Database=master;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;

Różni użytkownicy Windows mogą mieć prywatne instancje o tej samej nazwie. Sama nazwa nie identyfikuje instancji innego użytkownika.

Współdzielona instancja ma alias widoczny dla innych użytkowników na tym samym komputerze. Administrator musi skonfigurować udostępnianie, a inni użytkownicy potrzebują odpowiedniego logowania do Windows lub SQL. Udostępnianie nie przyznaje automatycznie uprawnień do bazy danych. Użyj wspólnej przestrzeni nazw:

Server=(localdb)\.\<shared_instance>;Database=<database>;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;

Udostępniaj instancję deweloperską tylko celowo. Sprawdź dostęp do plików lokalnie i uprawnienia do bazy danych. Zobacz Współdzielone instancje LocalDB.

Uwagi

Użyj AttachDBFilename, aby dołączyć istniejący plik bazy danych, do którego właściciel instancji ma dostęp. Określ także nazwę bazy danych:

Server=(localdb)\MSSQLLocalDB;Database=<database>;AttachDBFilename=C:\Data\<database>.mdf;Integrated Security=true;Encrypt=true;TrustServerCertificate=true;

Użyj absolutnej ścieżki do pliku lub odpowiednio skonfigurowanej |DataDirectory| wartości. AttachDBFilename Nie tworzy brakującego pliku bazy danych. Silnik musi wspierać wersję pliku bazy danych, a inna instancja nie może już mieć tego pliku otwartego.

Jeśli pominiesz to Database przy dołączaniu pliku, baza danych zostanie usunięta z instancji LocalDB po zamknięciu aplikacji. Określ, Database kiedy chcesz mieć trwałą rejestrację bazy danych.

User Instance=true nie jest ważny dla LocalDB. Nie używaj MultiSubnetFailover=true z LocalDB; jego lokalne połączenie z nazwanym potokiem nie jest punktem awaryjnym protokołu Transmission Control Protocol (TCP).

Chroń bazę danych i pliki logów uprawnieniami do plików Windows. Osoba, która potrafi skopiować niechroniony plik bazy danych, może potencjalnie dołączyć go do instancji, którą kontroluje. Uprawnienia SQL nie zastępują ochrony systemu plików.

Programistyczne tworzenie nazwanego wystąpienia

Dotyczy: .NET Framework

Dla aplikacji .NET Framework zadeklaruj nazwaną instancję oraz jej zainstalowaną wersję silnika LocalDB w system.data.localdb sekcji app.config. Zarejestruj typ sekcji konfiguracji Microsoft.Data.SqlClient z zestawu Microsoft.Data.LocalDBConfigurationSection, a następnie dodaj instancję pod localdbinstances.

Dopasuj nazwę instancji do Server=(localdb)\<instance> wpisu konfiguracji i użyj wersji silnika LocalDB zainstalowanej na komputerze. Nie kopiuj starej wersji sterownika w asemblerze lub wersji silnika do nowej aplikacji.

Nowoczesny .NET nie używa tej sekcji konfiguracji do tworzenia instancji. Używaj SqlLocalDB podczas konfiguracji dewelopera lub API zarządzania LocalDB , gdy aplikacja musi zarządzać instancją.

Limitations

LocalDB działa z uprawnieniami właściciela instancji. Jest przeznaczony do rozwoju lokalnego, a nie do wspólnej usługi produkcyjnej.

• LocalDB działa tylko na Windows. Połączenie LocalDB z zarządzaną obsługą sieci na platformie innej niż Windows powoduje wystąpienie błędu PlatformNotSupportedException.
• Zdalne zarządzanie nie jest obsługiwane.
• Użycie funkcji FILESTREAM i przez subskrybentów replikacji scalającej nie jest obsługiwane.
• Service Broker obsługuje tylko lokalne kolejki.
• Rozmiar bazy danych i limity zasobów są zgodne z zainstalowanym silnikiem SQL Server Express, a nie z wersji pakietu SqlClient.

Zobacz limity edycji dla SQL Server 2022 i SQL Server 2025. Testy LocalDB nie obejmują uwierzytelniania Microsoft Entra, zdalnej weryfikacji certyfikatów protokołu Transport Layer Security (TLS), przełączenia awaryjnego grupy dostępności ani ograniczeń usług chmurowych. Przetestuj je osobno w kontekście docelowego wdrożenia.

Treści powiązane

• Funkcje i ADO.NET programu SQL Server
• Narzędzie SqlLocalDB
• SQL Server i uwierzytelnianie systemu Windows
• Najlepsze rozwiązania dotyczące zabezpieczeń