LocalDB и локальная разработка с помощью SqlClient

Скачать ADO.NET

SQL Server Express LocalDB — это лёгкий движок SQL Server для локальной разработки Windows. Он работает под вашим именем пользователя Windows и запускается по запросу. LocalDB — это не удалённый сервис баз данных и не работает на Linux или macOS.

Для кроссплатформенной разработки используйте поддерживаемый контейнер SQL Server или удалённую SQL-конечную точку. Установка Microsoft.Data.SqlClient пакета NuGet устанавливает драйвер клиента, а не LocalDB.

Установка LocalDB

Установите LocalDB через SQL Server Express или через установщик Visual Studio. В Visual Studio выберите соответствующую нагрузку для разработки данных или отдельный компонент SQL Server Express LocalDB. См. установка SQL Server Express LocalDB для получения сведений об актуальных вариантах загрузки и установки.

Установка LocalDB обеспечивает движок, SQLUserInstance.dll, и утилиту управления SqlLocalDB.exe. Если SqlLocalDB отсутствует на PATH, запустите его из каталога установленных средств SQL Server.

Перечислите установленные версии и экземпляры:

SqlLocalDB versions
SqlLocalDB info

Подключитесь к автоматическому экземпляру

Автоматический экземпляр называется MSSQLLocalDB и принадлежит текущему пользователю Windows. Используйте интегрированную аутентификацию Windows. LocalDB не поддерживает аутентификацию Microsoft Entra.

Для консольного приложения .NET с 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());

Запрос выводит master. Первое соединение может занять больше времени, потому что LocalDB создаёт или запускает экземпляр. Если время запуска превышает тайм-аут соединения, проверьте статус экземпляра, дождитесь завершения запуска и попробуйте снова.

Этот пример разрешает использовать сертификат локальной разработки с TrustServerCertificate=true. Ограничьте применение этого исключения только локальной разработкой. Для удалённой SQL-точки используйте проверяемый сертификат и TrustServerCertificate=false; см. Шифрование и проверка сертификатов.

Обратные косые черты в строках соединения

Значение строки подключения содержит одну обратную косую черту между (localdb) и именем экземпляра. Побег зависит от того, где вы записываете значение:

Location Серверное значение
Обычный текст, конфигурация на расширяемом языке разметки (XML) или строка PowerShell в одинарных кавычках. (localdb)\MSSQLLocalDB
дословная строка в C# @"(localdb)\MSSQLLocalDB"
Обычная строка C# или строка JavaScript Object Notation (JSON). "(localdb)\\MSSQLLocalDB"

Не копируйте удвоенные обратные слеши C# в обычную текстовую строку подключения.

Именованные и совместно используемые экземпляры

Используйте именованный экземпляр, если хотите отдельный локальный экземпляр движка для приложения. Создайте его перед подключением:

SqlLocalDB create SqlClientDev
SqlLocalDB start SqlClientDev
SqlLocalDB info SqlClientDev

Подключитесь с помощью этой строки подключения в виде обычного текста:

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

Разные пользователи Windows могут иметь приватные экземпляры с одинаковым именем. Одного имени недостаточно, чтобы идентифицировать экземпляр другого пользователя.

Общий экземпляр имеет псевдоним, видимый другим пользователям на том же компьютере. Администратор должен настроить совместный доступ, а другим пользователям — соответствующий вход в Windows или SQL. Обмен не даёт автоматически права на базу данных. Используйте общее пространство имён:

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

Предоставляйте доступ к экземпляру для разработки только осознанно. Проверьте доступ к локальным файлам и права на базу данных. См. раздел Общие экземпляры LocalDB.

Замечания

Используйте AttachDBFilename для прикрепления существующего файла базы данных, к которому владелец экземпляра может получить доступ. Также укажите имя базы данных:

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

Используйте абсолютный путь к файлу или правильно настроенное |DataDirectory| значение. AttachDBFilename не создает отсутствующий файл базы данных. Движок должен поддерживать версию файла базы данных, и другой экземпляр не может уже иметь файл открытым.

Если при присоединении файла пропустить Database, база данных будет удалена из экземпляра LocalDB при закрытии приложения. Укажите Database , когда вам нужна постоянная регистрация базы данных.

User Instance=true не действит для LocalDB. Не используйте MultiSubnetFailover=true с LocalDB; его локальное именованный канал не является конечной точкой отказа по протоколу управления передачей (TCP).

Защитите базу данных и файлы журналов с помощью разрешений для файлов Windows. Человек, который может скопировать незащищённый файл базы данных, может потенциально прикрепить его к контролируемому им экземпляру. Разрешения SQL не заменяют защиту файловой системы.

Программное создание именованного экземпляра

Область применения: .NET Framework

Для приложения .NET Framework объявите именованный экземпляр и его установленную версию движка LocalDB в разделе system.data.localdbapp.config. Зарегистрируйте тип раздела конфигурации Microsoft.Data.LocalDBConfigurationSection из сборки Microsoft.Data.SqlClient, а затем добавьте экземпляр в разделе localdbinstances.

Сопоставьте имя Server=(localdb)\<instance> экземпляра с записью конфигурации и используйте версию движка LocalDB, установленную на компьютере. Не копируйте старую версию сборки драйвера или движка в новое приложение.

Современный .NET не использует этот раздел конфигурации для создания экземпляров. Используйте SqlLocalDB при настройке разработчиком или API управления LocalDB , когда приложению необходимо управлять экземпляром.

Limitations

LocalDB работает с разрешениями владельца экземпляра. Он предназначен для локального развития, а не для совместного производства.

  • LocalDB работает только для Windows. Управляемое сетевое соединение LocalDB на платформе вне Windows выдает PlatformNotSupportedException.
  • Удалённое управление не поддерживается.
  • Использование подписчиков FILESTREAM и merge-replication не поддерживается.
  • Service Broker поддерживает только локальные очереди.
  • Размер базы данных и ограничения ресурсов соответствуют установленному движку SQL Server Express, а не версии пакета SqlClient.
Engine Максимальные вычислительные ресурсы на экземпляр Максимальный пул буфера в мегабайтах (МБ) Максимальный размер реляционной базы данных в гигабайтах (GB)
SQL Server 2022 Express LocalDB. Меньше одного сокета или 4 ядер. 1 410 МБ. 10 ГБ.
SQL Server 2025 Express LocalDB. Меньше одного сокета или 4 ядер. 1 410 МБ. 50 ГБ.

Смотрите ограничения по версиям SQL Server 2022 и SQL Server 2025. Тестирование LocalDB не включает аутентификацию Microsoft Entra, проверку сертификатов удалённого транспортного уровня безопасности (TLS), резервное переключение группы доступности или ограничения облачных сервисов. Тестируйте их по отдельности в целевой среде развертывания.

Связанные материалы

  • Последнее обновление: