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

2025-06-11

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

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

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

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

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

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

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 сервер и экземпляр базы данных (переменная postgresdb) используется для добавления зависимости к ExampleProject.

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

Ресурс сервера PostgreSQL включает учетные данные по умолчанию с username, равным "postgres", и случайно созданными password с использованием метода CreateDefaultPasswordParameter.

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

Совет

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

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

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

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

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

var builder = DistributedApplication.CreateBuilder(args);

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

var databaseName = "app_db";
var creationScript = $$"""
    -- Create the database
    CREATE DATABASE {{databaseName}};

    """;

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

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

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

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

Замечание

Подключение к команде базы данных (\c) не поддерживается при использовании скрипта создания.

Добавьте ресурс 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: Томы.

Важный

Некоторые интеграции баз данных, включая интеграцию .NET AspirePostgreSQL, не могут успешно использовать тома данных после развертывания в Azure Container Apps (ACA). Это связано с тем, что ACA использует Server блок сообщений (SMB) для подключения контейнеров к томам данных, а некоторые системы не могут использовать это подключение. Aspire На панели мониторинга база данных, затронутая этой проблемой, имеет состояние "Активация" или "Сбой активации", но никогда не отображается как "Запущен".

Эту проблему можно устранить с помощью управляемой базы данных службыAzure для PostgreSQL размещения развернутой базы данных вместо контейнера в ACA, что является рекомендуемом подходом независимо от этой проблемы. В следующем коде узла приложения показано, как развернуть базу данных в Azure базе данных для PostgreSQL, но в процессе разработки запустить её как контейнер с томом данных.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer(container => 
                      {
                        container.WithDataVolume();
                      });

builder.Build().Run();

Добавить ресурс сервера 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 опирается на файловую систему хост-компьютера для инициализации базы данных сервера с использованием папки 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.

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

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