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

2025-02-07

Включает: интеграция хостинга — и — Client Интеграция

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

Хостинговая интеграция

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

.NET интерфейс командной строки
СсылкаНаПакет

dotnet add package Aspire.Hosting.SqlServer

<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>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

Заметка

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

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

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

Ресурс 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 со скриптами базы данных

По умолчанию при добавлении SqlServerDatabaseResourceон использует следующий скрипт SQL для создания базы данных:

IF
(
    NOT EXISTS
    (
        SELECT 1
        FROM sys.databases
        WHERE name = @DatabaseName
    )
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];

Чтобы изменить скрипт по умолчанию, выполните цепочку последовательных вызовов метода WithCreationScript на построителе ресурсов базы данных.

var builder = DistributedApplication.CreateBuilder(args);

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

var databaseName = "app-db";
var creationScript = $$"""
    IF DB_ID('{{databaseName}}') IS NULL
        CREATE DATABASE [{{databaseName}}];
    GO

    -- Use the database
    USE [{{databaseName}}];
    GO

    -- Create the todos table
    CREATE TABLE todos (
        id INT PRIMARY KEY IDENTITY(1,1),        -- Unique ID for each todo
        title VARCHAR(255) NOT NULL,             -- Short description of the task
        description TEXT,                        -- Optional detailed description
        is_completed BIT DEFAULT 0,              -- Completion status
        due_date DATE,                           -- Optional due date
        created_at DATETIME DEFAULT GETDATE()    -- Creation timestamp
    );
    GO

    """;

var db = sql.AddDatabase(databaseName)
            .WithCreationScript(creationScript);

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

В предыдущем примере создается база данных с именем app_db, содержащая одну таблицу todos. Скрипт SQL выполняется при создании ресурса базы данных. Скрипт передается в виде строки WithCreationScript в метод, который затем выполняется в контексте SQL Server ресурса.

Добавьте ресурс 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

Объём данных используется для сохранения 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

Важный

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

Подключения привязки данных зависят от файловой системы хост-компьютера для сохранения 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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

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

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

SQL Server Студия управления
MSSQL для Visual Studio Code

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

Откройте SSMS.
В диалоговом окне Подключение к Server выберите вкладку Дополнительные параметры подключения.
Вставьте строку подключения в поле Дополнительные параметры подключения и выберите Connect.
Если вы подключены, вы увидите ресурс базы данных в обозревателе объектов :

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

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

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

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

интеграция Client

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

.NET интерфейс командной строки
СсылкаНаПакет

dotnet add package Aspire.Microsoft.Data.SqlClient

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

Добавьте клиента SQL Server

В файле Program.cs проекта, используемого клиентом, вызовите метод расширения 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 Server

Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров 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 ServerJSON см. в разделе 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 репозиторий
Azure Примеры SQL и SQL ServerAspire