интеграция .NET AspireAzurePostgreSQL

Статья
02/19/2025

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

Azure База данных для PostgreSQL— гибкая Server — это служба реляционной базы данных на основе ядра СУБД с открытым исходным кодом Postgres. Это полностью управляемая база данных как услуга, которая может обрабатывать критически важные рабочие нагрузки с прогнозируемой производительностью, безопасностью, высокой доступностью и динамической масштабируемостью. Интеграция .NET AspireAzurePostgreSQL позволяет подключаться к существующим базам данных AzurePostgreSQL или создавать новые экземпляры из .NET с помощью docker.io/library/postgres образа контейнера.

Интеграция хостинга

.NET Aspire Azure PostgreSQL интеграция моделирует гибкий сервер и базу данных PostgreSQL в качестве типов AzurePostgresFlexibleServerResource и AzurePostgresFlexibleServerDatabaseResource. Другие типы, которые изначально доступны в интеграции хостинга, представлены в следующих ресурсах.

Чтобы получить доступ к этим типам и API для выражения их в виде ресурсов в проекте приложения, установите 📦Aspire. Хостинг.Azure. пакет NuGetPostgreSQL:

.NET Командный интерфейс
PackageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Дополнительную информацию см. в разделе dotnet add package.

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

Дополнительную информацию см. в разделе Управление зависимостями пакетов в .NET приложениях.

Интеграция размещения AzurePostgreSQL зависит от 📦Aspire.HostingPostgreSQL пакета NuGet, который расширяют для поддержки Azure. Все, что можно сделать с помощью .NET AspirePostgreSQL и .NET AspirePostgreSQLEntity Framework Core интеграции, можно также сделать с помощью этой интеграции.

Добавление ресурса сервера AzurePostgreSQL

После установки интеграции хостинга .NET AspireAzurePostgreSQL вызовите метод расширения AddAzurePostgresFlexibleServer в проекте хост-приложения:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

Предыдущий вызов AddAzurePostgresFlexibleServer настраивает ресурс сервера PostgreSQL для развертывания в качестве гибкой AzurePostgresServer.

Важный

По умолчанию AddAzurePostgresFlexibleServer настраивает аутентификацию с использованием идентификатора Microsoft Entra ID. Это требует изменений в приложениях, которые должны подключаться к этим ресурсам. Дополнительные сведения см. в Client интеграции.

Совет

При вызове AddAzurePostgresFlexibleServerнеявно вызывается AddAzureProvisioning, что обеспечивает возможность создания ресурсов Azure динамически при запуске приложения. Приложение должно настроить соответствующую подписку и местоположение. Дополнительные сведения см. в разделе Локальная подготовка: Конфигурация.

интеграция Client

Чтобы приступить к работе с интеграцией клиента .NET AspirePostgreSQL, установите 📦Aspire. Npgsql пакет NuGet в проекте, использующем клиент, то есть в проекте для приложения, использующего клиент PostgreSQL. Интеграция клиента PostgreSQL регистрирует экземпляр NpgsqlDataSource, который можно использовать для взаимодействия с PostgreSQL.

.NET Командный интерфейс
PackageReference

dotnet add package Aspire.Npgsql

<PackageReference Include="Aspire.Npgsql" Version="*" />

Добавление клиента Npgsql

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

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Совет

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

После добавления NpgsqlDataSource в построитель можно получить экземпляр NpgsqlDataSource с помощью внедрения зависимостей. Например, чтобы получить объект источника данных из примера службы, определите его как параметр конструктора и убедитесь, что класс ExampleService зарегистрирован в контейнере внедрения зависимостей:

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

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

Добавить клиент Npgsql с ключевым доступом

Могут возникнуть ситуации, когда требуется зарегистрировать несколько экземпляров NpgsqlDataSource с различными именами подключений. Чтобы зарегистрировать ключи клиентов Npgsql, вызовите метод AddKeyedNpgsqlDataSource:

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

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

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

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

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

Интеграция .NET AspirePostgreSQL предоставляет несколько подходов к конфигурации и вариантов для удовлетворения требований и соглашений проекта.

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

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

builder.AddNpgsqlDataSource("postgresdb");

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

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

Дополнительные сведения см. в ConnectionString.

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

Интеграция .NET AspirePostgreSQL поддерживает Microsoft.Extensions.Configuration. Он загружает NpgsqlSettings из appsettings.json или других файлов конфигурации с помощью ключа Aspire:Npgsql. Пример appsettings.json, который настраивает некоторые параметры:

В следующем примере показан файл appsettings.json, который настраивает некоторые доступные параметры:

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

Для полной схемы интеграции клиента PostgreSQLJSON см. в Aspire. Npgsql/ConfigurationSchema.json.

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

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

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

Client контроль состояния интеграции

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

.NET проверки работоспособности приложения на C#
проверка состояния в ASP.NET Core

Добавляет NpgSqlHealthCheck, который проверяет, можно ли успешно выполнять команды в базовой базе данных Postgres.
Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки работоспособности должны быть пройдены, чтобы приложение считалось готовым принять трафик.

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

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

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

Интеграция .NET AspirePostgreSQL использует следующие категории журналов:

Npgsql.Connection
Npgsql.Command
Npgsql.Transaction
Npgsql.Copy
Npgsql.Replication
Npgsql.Exception

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

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

Npgsql

Метрика

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

Npgsql:
- ec_Npgsql_bytes_written_per_second
- ec_Npgsql_bytes_read_per_second
- ec_Npgsql_commands_per_second
- ec_Npgsql_total_commands
- ec_Npgsql_current_commands
- ec_Npgsql_failed_commands
- ec_Npgsql_prepared_commands_ratio
- ec_Npgsql_connection_pools
- ec_Npgsql_multiplexing_average_commands_per_batch
- ec_Npgsql_multiplexing_average_write_time_per_batch

Добавьте клиента Npgsql с проверкой подлинности Azure

По умолчанию при вызове AddAzurePostgresFlexibleServer в интеграции размещения PostgreSQL он настраивает 📦Azure. Удостоверение пакет NuGet для включения проверки подлинности:

.NET Командный интерфейс
PackageReference

dotnet add package Azure.Identity

<PackageReference Include="Azure.Identity"
                  Version="*" />

Подключение PostgreSQL можно использовать с помощью интеграции клиента и Azure.Identity:

builder.AddNpgsqlDataSource(
    "postgresdb", 
    configureDataSourceBuilder: (dataSourceBuilder) =>
{
    if (!string.IsNullOrEmpty(dataSourceBuilder.ConnectionStringBuilder.Password))
    {
        return;
    }

    dataSourceBuilder.UsePeriodicPasswordProvider(async (_, ct) =>
    {
        var credentials = new DefaultAzureCredential();
        var token = await credentials.GetTokenAsync(
            new TokenRequestContext([
                "https://ossrdbms-aad.database.windows.net/.default"
            ]), ct);

        return token.Token;
    },
    TimeSpan.FromHours(24),
    TimeSpan.FromSeconds(10));
});

В приведенном выше фрагменте кода показано, как использовать класс DefaultAzureCredential из пакета Azure.Identity для проверки подлинности с помощью идентификатора Microsoft Entra ID и получения маркера для подключения к базе данных PostgreSQL. Метод UsePeriodicPasswordProvider используется для передачи токена в построитель строки подключения.

Поделиться через