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

Статья
12/12/2024

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

PostgreSQL — это мощная система реляционной базы данных с открытым исходным кодом с много лет активной разработки, которая заработала сильную репутацию для надежности, надежности функций и производительности. Интеграция .NET AspirePostgreSQL позволяет подключаться к существующим базам данных PostgreSQL или создавать новые экземпляры из .NET с помощью образа контейнера docker.io/library/postgres.

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

PostgreSQL интеграция моделирует PostgreSQLserver как тип PostgresServerResource. Чтобы получить доступ к этому типу и API, которые позволяют добавить его в пакет NuGet 📦Aspire. Хостинг.PostgreSQL в проекте хоста приложения .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

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

Добавить ресурс PostgreSQLserver

В проекте узла приложения вызовите AddPostgres в экземпляре builder, чтобы добавить ресурс PostgreSQLserver, а затем вызовите AddDatabase в экземпляре postgres, чтобы добавить ресурс базы данных, как показано в следующем примере:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Когда .NET.NET Aspire добавляет образ контейнера в узел приложения, как показано в предыдущем примере с изображением docker.io/library/postgres, он создает новый экземпляр PostgreSQLserver на локальном компьютере. Ссылка на PostgreSQLserver и экземпляр базы данных PostgreSQL (переменная postgresdb) используются для добавления зависимости в ExampleProject. Ресурс PostgreSQLserver включает учетные данные по умолчанию с username для "postgres" и случайно созданными password с помощью метода CreateDefaultPasswordParameter.

Метод WithReference настраивает подключение в ExampleProject с именем "messaging". Дополнительные сведения см. в жизненном цикле ресурсов контейнера.

Совет

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

Добавьте ресурс pgAdmin PostgreSQL

При добавлении PostgreSQL ресурсов в builder с помощью метода AddPostgres можно выполнить цепочку вызовов WithPgAdmin, чтобы добавить контейнер dpage/pgadmin4. Этот контейнер является кроссплатформенным решением client для баз данных PostgreSQL, которое служит веб-основанной административной панелью управления. Рассмотрим следующий пример:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin();

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

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

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

Приведенный выше код добавляет контейнер на основе образа docker.io/dpage/pgadmin4. Контейнер используется для управления PostgreSQLserver и ресурсами базы данных. Метод WithPgAdmin добавляет контейнер, который служит веб-панелью мониторинга администрирования для PostgreSQL баз данных.

Добавьте ресурс pgWeb PostgreSQL

При добавлении ресурсов PostgreSQL в builder с использованием метода AddPostgres вы можете организовать цепочку вызовов WithPgWeb, чтобы добавить контейнер sosedoff/pgweb. Этот контейнер представляет собой кроссплатформенную client для баз данных PostgreSQL, которая служит веб-панелью управления. Рассмотрим следующий пример:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb();

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

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

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

Приведенный выше код добавляет контейнер на основе образа docker.io/sosedoff/pgweb. Все зарегистрированные экземпляры PostgresDatabaseResource используются для создания файла конфигурации для каждого экземпляра, и каждая конфигурация привязана к каталогу закладок pgweb контейнера. Дополнительные сведения см. в документации PgWeb: Server закладки подключений.

Добавление ресурса с идентификаторами PostgreSQLиserver, с объемом данных

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

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume(isReadOnly: false);

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

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

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

Том данных используется для сохранения PostgreSQLserver данных за пределами жизненного цикла контейнера. Том данных подключается по пути /var/lib/postgresql/data в контейнере PostgreSQLserver и когда параметр name не указан, имя создается случайным образом. Дополнительная информация о томах данных и причинах, по которым они предпочтительнее привязок, приведена в документации Docker: Томы.

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

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

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataBindMount(
                          source: @"C:\PostgreSQL\Data",
                          isReadOnly: false);

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

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

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

Важный

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

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

Добавление ресурса PostgreSQLserver с подключением привязки init

Чтобы добавить подключение привязки init к ресурсу PostgreSQLserver, вызовите метод WithInitBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithInitBindMount(@"C:\PostgreSQL\Init");

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

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

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

Подключение привязки для инициализации (init bind mount) зависит от файловой системы хост-компьютера для инициализации базы данных PostgreSQLserver с использованием папки инициализации контейнера . Эта папка используется для инициализации, запуская все исполняемые скрипты оболочки или файлы команд .sql после создания папки -data. Точка монтирования init монтируется на C:\PostgreSQL\Init в Windows (или /PostgreSQL/Init на Unix) на хост-компьютере в контейнере PostgreSQLserver.

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

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

var builder = DistributedApplication.CreateBuilder(args);

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

var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");

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

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

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

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

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

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

интеграция Client

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

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

dotnet add package Aspire.Npgsql

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

Добавить Npgsql client

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

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Совет

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

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

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

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

Добавить Npgsql с ключами client

Могут возникнуть ситуации, когда вам может понадобиться зарегистрировать несколько экземпляров 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
    }
  }
}

Полной схеме интеграции PostgreSQLclientJSON см. в Aspire. Npgsql/ConfigurationSchema.json.

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

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

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

Проверка здоровья

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

Добавляет 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

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

Чтобы развернуть ресурсы PostgreSQL в Azure, установите 📦Aspire. Хостинг.Azure. пакет NuGetPostgreSQL:

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

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

После установки интеграции хостинга .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 настраивает ресурс PostgresSQL server для развертывания в качестве AzurePostgres гибкой Server.

Важный

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

Добавить Azure аутентифицированные Npgsql client

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

.NET CLI
PackageReference

dotnet add package Azure.Identity

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

Подключение PostgreSQL может быть использовано с помощью интеграции client и 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 используется для передачи токена конструктору строк подключения.

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

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

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

Добавить ресурс PostgreSQLserver

Добавьте ресурс pgAdmin PostgreSQL

Добавьте ресурс pgWeb PostgreSQL

Добавление ресурса с идентификаторами PostgreSQLиserver, с объемом данных

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

Добавление ресурса PostgreSQLserver с подключением привязки init

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

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

интеграция Client

Добавить Npgsql client

Добавить Npgsql с ключами client

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

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

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

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

Проверка здоровья

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

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

Трассировка

Метрика

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

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

Добавить Azure аутентифицированные Npgsql client

См. также

Дополнительные ресурсы