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

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

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

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

Интеграция PostgreSQL хостинга моделирует различные PostgreSQL ресурсы как следующие типы.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Чтобы получить доступ к этим типам и API для выражения их в виде ресурсов в вашем проекте хоста приложения, установите пакет NuGet 📦Aspire.Hosting.PostgreSQL:

dotnet add package Aspire.Hosting.PostgreSQL

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

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

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

В проекте узла приложения вызовите AddPostgres в экземпляре builder, чтобы добавить ресурс сервера PostgreSQL, а затем вызовите 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, он создает новый экземпляр сервера PostgreSQL на локальном компьютере. Ссылка на сервер PostgreSQL и экземпляр базы данных PostgreSQL (переменная postgresdb) используются для добавления зависимости в ExampleProject. Ресурс сервера PostgreSQL включает учетные данные по умолчанию с username, равным "postgres", и случайно созданными password с использованием метода CreateDefaultPasswordParameter.

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

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

При добавлении PostgreSQL ресурсов в builder с помощью метода AddPostgres можно выполнить цепочку вызовов WithPgAdmin, чтобы добавить контейнер dpage/pgadmin4. Этот контейнер представляет собой кроссплатформенный клиент для баз данных 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. Контейнер используется для управления ресурсами сервера и базы данных PostgreSQL. Метод WithPgAdmin добавляет контейнер, который служит веб-панелью мониторинга администрирования для PostgreSQL баз данных.

Настройка порта узла pgAdmin

Чтобы настроить порт узла для контейнера pgAdmin, вызовите метод WithHostPort в ресурсе сервера PostgreSQL. В следующем примере показано, как настроить порт узла для контейнера pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));

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

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

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

Приведенный выше код добавляет и настраивает порт узла для контейнера pgAdmin. Порт узла в противном случае назначается случайным образом.

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

При добавлении ресурсов PostgreSQL в builder с использованием метода AddPostgres вы можете организовать цепочку вызовов WithPgWeb, чтобы добавить контейнер sosedoff/pgweb. Этот контейнер представляет собой кроссплатформенный клиент для баз данных 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 закладки подключений.

Настройка порта узла pgWeb

Чтобы настроить порт узла для контейнера pgWeb, вызовите метод WithHostPort в ресурсе сервера PostgreSQL. В следующем примере показано, как настроить порт узла для контейнера pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb(pgWeb => pgWeb.WithHostPort(5050));

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

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

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

Приведенный выше код добавляет и настраивает порт узла для контейнера pgWeb. Порт узла в противном случае назначается случайным образом.

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

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

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...

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

Добавить ресурс сервера PostgreSQL с привязкой данных

Чтобы добавить привязку данных к ресурсу сервера PostgreSQL, вызовите метод 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...

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

Добавление ресурса сервера PostgreSQL с использованием монтирования типа bind для инициализации

Чтобы добавить привязку инициализации к ресурсу сервера PostgreSQL, вызовите метод 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 опирается на файловую систему хост-компьютера для инициализации базы данных сервера с использованием папки init контейнеров PostgreSQL. Эта папка используется для инициализации и запуска всех исполняемых скриптов оболочки или файлов команд .sql после создания папки postgres-data. Монтирование привязки init выполнено на C:\PostgreSQL\Init в системе Windows (или на /PostgreSQL/Init в Unix) на пути хост-компьютера в серверном контейнере PostgreSQL.

Добавление ресурса сервера PostgreSQL с параметрами

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

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

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

интеграция Client

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

dotnet add package Aspire.Npgsql

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

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

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

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

После добавления 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

См. также

• PostgreSQL документы
• .NET Aspire Azure PostgreSQL интеграция
• интеграции .NET.NET Aspire
• .NET Aspire GitHub репозиторий