интеграция .NET AspireSQL Server

Включает:интеграция размещения и Client интеграции

SQL Server — это реляционная система управления базами данных, разработанная корпорацией Майкрософт. Интеграция .NET AspireSQL Server позволяет подключаться к существующим экземплярам SQL Server или создавать новые экземпляры из .NET с помощью образа контейнера mcr.microsoft.com/mssql/server.

Интеграция размещения

SQL Server хостинговая интеграция моделирует server как тип SqlServerServerResource, а базу данных как тип SqlServerDatabaseResource. Чтобы получить доступ к этим типам и API, добавьте 📦Aspire.Hosting.SqlServer пакет NuGet в проект узла приложения .

.NET CLI (интерфейс командной строки)

dotnet add package Aspire.Hosting.SqlServer

PackageReference

<PackageReference Include="Aspire.Hosting.SqlServer"
                  Version="*" />

Дополнительные сведения см. в статьях dotnet add package или управление зависимостями пакетов в приложениях .NET.

Добавление ресурса SQL Server и ресурса базы данных

В проекте узла приложения вызовите AddSqlServer, чтобы добавить и вернуть построитель ресурсов SQL Server. Присоедините вызов к возвращаемому построителю ресурсов для AddDatabase, чтобы добавить ресурс базы данных SQL Server.

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Заметка

Контейнер SQL Server медленно запускается, поэтому рекомендуется использовать постоянное время существования, чтобы избежать ненужных перезапусков. Дополнительные сведения см. в времени жизни ресурса контейнера.

Когда .NET.NET Aspire добавляет образ контейнера в хост приложения, как показано в предыдущем примере с образом mcr.microsoft.com/mssql/server, он создает новый экземпляр SQL Server на локальном компьютере. Ссылка на построитель ресурсов SQL Server (переменная sql) используется для добавления базы данных. База данных называется database, а затем добавляется в ExampleProject. Ресурс SQL Server включает учетные данные по умолчанию с параметром username, равным sa, и случайным значением password, сгенерированным с использованием метода CreateDefaultPasswordParameter.

При запуске хоста приложения пароль хранится в хранилище секретов хоста приложения. Он добавлен в раздел Parameters, например:

{
  "Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}

Имя параметра — sql-password, но на самом деле это просто форматирование имени ресурса с -password суффиксом. Дополнительные сведения см. в разделе Безопасное хранение секретов приложений в разработке в ASP.NET Core и Добавление ресурса SQL Server с параметрами.

Метод WithReference настраивает подключение в ExampleProject с именем database.

Совет

Если вы хотите подключиться к существующей SQL Server, вызовите AddConnectionString вместо этого. Дополнительные сведения см. в статье Справочник по существующим ресурсам.

Добавьте ресурс SQL Server с объемом данных

Чтобы добавить том данных в ресурс SQL Server, вызовите метод WithDataVolume в ресурсе SQL Server:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataVolume();

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Том данных используется для сохранения SQL Server данных за пределами жизненного цикла контейнера. Том данных монтируется по пути /var/opt/mssql в контейнере SQL Server, и когда параметр name не указан, имени присваивается случайное значение. Дополнительные сведения о томах данных и сведения о том, почему они предпочтительнее привязки, см. в Docker документации по томам.

Предупреждение

Пароль хранится в томе данных. При использовании тома данных и при изменении пароля он не будет работать, пока не удалите том.

Добавление ресурса SQL Server с подключением привязки данных

Чтобы добавить подключение привязки данных к ресурсу SQL Server, вызовите метод WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataBindMount(source: @"C:\SqlServer\Data");

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Важный

Подключения привязки данных имеют ограниченные функциональные возможности по сравнению с томами, которые обеспечивают более высокую производительность, переносимость и безопасность, что делает их более подходящими для рабочих сред. Однако привязываемые подключения позволяют напрямую получать доступ и изменять файлы в хост-системе, идеально подходит для разработки и тестирования, в которых требуются изменения в режиме реального времени.

Подключения привязки данных зависят от файловой системы хост-компьютера для сохранения SQL Server данных во время перезапуска контейнера. Точка привязки данных монтируется в C:\SqlServer\Data в Windows (или /SqlServer/Data на Unix) пути на хост-компьютере в контейнере SQL Server. Дополнительные сведения о монтировании данных см. в документации по Docker: монтирование данных.

Добавить ресурс SQL Server с параметрами

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

var builder = DistributedApplication.CreateBuilder(args);

var password = builder.AddParameter("password", secret: true);

var sql = builder.AddSqlServer("sql", password);
var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

// After adding all resources, run the app...

Дополнительные сведения о предоставлении параметров см. в разделе Внешние параметры.

Подключение к ресурсам базы данных

При запуске хоста приложения .NET Aspire к ресурсам базы данных serverможно получить доступ из внешних инструментов, таких как SQL Server Management Studio (SSMS) или Azure Data Studio. Строка подключения для ресурса базы данных доступна в средовых переменных зависимых ресурсов и может быть найдена с использованием панели мониторинга .NET.NET Aspire: в области сведений о ресурсах. Переменная среды называется ConnectionStrings__{name}, где {name} — имя ресурса базы данных, в этом примере это database. Используйте строку подключения для подключения к ресурсу базы данных из внешних средств. Представьте, что у вас есть база данных с именем todos с одной таблицей dbo.Todos.

SQL Server Студия управления

Чтобы подключиться к ресурсу базы данных из SQL Server Management Studio, выполните следующие действия.

1. Откройте SSMS.

2. В диалоговом окне Подключение к Server выберите вкладку Дополнительные параметры подключения.

3. Вставьте строку подключения в поле Дополнительные параметры подключения и выберите Connect.

   

4. Если вы подключены, вы увидите ресурс базы данных в обозревателе объектов :

   

Дополнительные сведения см. в статье SQL Server Management Studio: подключение к server.

Azure Data Studio

Чтобы подключиться к ресурсу базы данных из Azure Data Studio, выполните следующие действия.

1. Откройте Azure Data Studio.

2. Выберите раскрывающийся список "Новый" и выберите "Новое подключение".

   

3. Измените тип ввода на строку подключения и вставьте строку подключения в поле строки подключения.

4. Выберите , затем подключитесь.

   

5. Если вы подключены, вы увидите ресурс базы данных на активной вкладке:

   

Дополнительные сведения см. в разделе Azure Data Studio: подключение к SQL Server.

Проверка работоспособности хостинговой интеграции

Интеграция хостинга SQL Server автоматически добавляет ресурс SQL Server для проверки работоспособности. Проверка состояния проверяет, запущен ли SQL Server и можно ли установить с ним подключение.

Интеграция размещения зависит от пакета NuGet 📦 AspNetCore.HealthChecks.SqlServer.

интеграция Client

Чтобы приступить к работе с интеграцией .NET AspireSQL Serverclient, установите пакет NuGet 📦AspireMicrosoft.Data.SqlClient в проекте, использующем client, то есть в проекте приложения с использованием SQL Serverclient. Интеграция SQL Serverclient регистрирует экземпляр SqlConnection, который можно использовать для взаимодействия с SQL Server.

.NET CLI (интерфейс командной строки)

dotnet add package Aspire.Microsoft.Data.SqlClient

PackageReference

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

Добавьте SQL Serverclient

В файле Program.cs проекта client-потребления вызовите метод расширения AddSqlServerClient на любом IHostApplicationBuilder, чтобы зарегистрировать SqlConnection для использования с помощью контейнера внедрения зависимостей. Метод принимает параметр имени подключения.

builder.AddSqlServerClient(connectionName: "database");

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса базы данных SQL Server в проект узла приложения. Другими словами, при вызове AddDatabase и указании имени database то же имя следует использовать при вызове AddSqlServerClient. Дополнительные сведения см. в разделе «Добавление SQL Server ресурса и ресурса базы данных».

Затем можно получить экземпляр SqlConnection с помощью внедрения зависимостей. Например, чтобы получить подключение из примера службы:

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

Дополнительные сведения о внедрении зависимостей см. в .NETвнедрение зависимостей.

Добавьте ключ SQL Serverclient

Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров SqlConnection, каждый с уникальным именем подключения. Чтобы зарегистрировать клиентов с ключами SQL Server, вызовите метод AddKeyedSqlServerClient.

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

Важный

При использовании ключевых служб ожидается, что ресурс SQL Server настраивает две именованные базы данных, одну для mainDb и одну для loggingDb.

Затем вы сможете извлечь экземпляры SqlConnection с помощью внедрения зависимостей. Например, чтобы получить подключение из службы-примера:

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

Дополнительные сведения о ключевых службах см. в разделе .NET внедрение зависимостей: ключевые службы.

Конфигурация

Интеграция .NET AspireSQL Server предоставляет несколько вариантов настройки подключения на основе требований и соглашений проекта.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове метода AddSqlServerClient:

builder.AddSqlServerClient(connectionName: "sql");

Затем строка подключения извлекается из раздела конфигурации ConnectionStrings:

{
  "ConnectionStrings": {
    "database": "Data Source=myserver;Initial Catalog=master"
  }
}

Дополнительные сведения о форматировании этой строки подключения см. в разделе ConnectionString.

Использование поставщиков конфигураций

Интеграция .NET AspireSQL Server поддерживает Microsoft.Extensions.Configuration. Он загружает MicrosoftDataSqlClientSettings из конфигурации, используя ключ Aspire:Microsoft:Data:SqlClient. Следующий фрагмент кода является примером файла appsettings.json, который настраивает некоторые параметры:

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

Для полной интеграционной схемы SQL ServerclientJSON см. Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Использование встроенных делегатов

Кроме того, можно передать делегат Action<MicrosoftDataSqlClientSettings> configureSettings, чтобы настроить некоторые или все встроенные параметры, например отключить проверку работоспособности из кода:

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

Client проверки работоспособности интеграции

По умолчанию .NET.NET Aspire интеграции включают проверки работоспособности для всех служб. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.

Интеграция .NET AspireSQL Server:

• Добавляет проверку работоспособности, когда MicrosoftDataSqlClientSettings.DisableHealthChecks находится в состоянии false, которая пытается подключиться к SQL Server.
• Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные тесты готовности должны быть пройдены для того, чтобы приложение считалось готовым принять трафик.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации журналов, трассировки и метрик, которые иногда называются основами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция .NET AspireSQL Server в настоящее время не включает ведение журнала по умолчанию из-за ограничений Microsoft.Data.SqlClient.

Отслеживание

Интеграция .NET AspireSQL Server выдает следующие действия трассировки с помощью OpenTelemetry:

• OpenTelemetry.Instrumentation.SqlClient

Метрика

Интеграция .NET AspireSQL Server будет выдавать следующие метрики с помощью OpenTelemetry:

• Microsoft.Data.SqlClient.EventSource
  • active-hard-connections
  • hard-connects
  • hard-disconnects
  • active-soft-connects
  • soft-connects
  • soft-disconnects
  • number-of-non-pooled-connections
  • number-of-pooled-connections
  • number-of-active-connection-pool-groups
  • number-of-inactive-connection-pool-groups
  • number-of-active-connection-pools
  • number-of-inactive-connection-pools
  • number-of-active-connections
  • number-of-free-connections
  • number-of-stasis-connections
  • number-of-reclaimed-connections

См. также

• Azure базы данных SQL
• SQL Server
• пример контейнеров базы данных .NET.NET Aspire
• интеграции .NET.NET Aspire
• .NET Aspire GitHub репозиторий