интеграция .NET AspirePostgreSQLEntity Framework Core

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

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

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

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

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

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

.NET CLI

dotnet add package Aspire.Hosting.PostgreSQL

PackageReference

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

Совет

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

Добавление ресурса 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")
                      .WithPgAdmin(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 зависит от файловой системы хост-компьютера для инициализации базы данных сервера с помощью папки инициализации контейнеров . Эта папка используется для инициализации и запуска всех исполняемых скриптов оболочки или файлов команд .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 AspirePostgreSQLEntity Framework Core, установите 📦AspireNpgsql.EntityFrameworkCore.PostgreSQL пакет NuGet в проект, который использует клиента, то есть для приложения, использующего клиента PostgreSQL. Интеграция клиента .NET AspirePostgreSQLEntity Framework Core регистрирует нужные экземпляры подклассов DbContext, которые можно использовать для взаимодействия с PostgreSQL.

.NET CLI

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

PackageReference

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

Добавьте контекст базы данных Npgsql

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

builder.AddNpgsqlDbContext<YourDbContext>(connectionName: "postgresdb");

Совет

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

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

public class ExampleService(YourDbContext context)
{
    // Use context...
}

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

Добавление контекста базы данных Npgsql с обогащением

Чтобы дополнить DbContext дополнительными службами, такими как автоматические повторные попытки, проверки работоспособности, ведение журнала и телеметрия, вызовите метод EnrichNpgsqlDbContext:

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

Параметр settings является экземпляром класса NpgsqlEntityFrameworkCorePostgreSQLSettings.

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

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

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

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

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

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

{
  "ConnectionStrings": {
    "pgdb": "Host=myserver;Database=test"
  }
}

EnrichNpgsqlDbContext не будет использовать раздел конфигурации ConnectionStrings, так как ожидается, что DbContext будет зарегистрирован в момент его вызова.

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

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

Интеграция .NET AspirePostgreSQLEntity Framework Core поддерживает Microsoft.Extensions.Configuration. Он загружает NpgsqlEntityFrameworkCorePostgreSQLSettings из файлов конфигурации, таких как appsettings.json с помощью ключа Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Если вы настроили конфигурации в разделе Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, можно просто вызвать метод без передачи любого параметра.

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

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

Полная схема интеграции клиента PostgreSQLEntity Framework CoreJSON смотрите в Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

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

Вы также можете передать делегат Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> для настройки некоторых или всех встроенных параметров, например, чтобы задать ConnectionString:

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

Настройка нескольких классов DbContext

Если вы хотите зарегистрировать несколько DbContext с другой конфигурацией, можно использовать имя раздела конфигурации $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". Конфигурация json будет выглядеть следующим образом:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

Затем вызов метода AddNpgsqlDbContext с параметром типа AnotherDbContext загрузит параметры из раздела Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Медицинские проверки

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

По умолчанию интеграция .NET AspirePostgreSQLEntity Framework Core обрабатывает следующие компоненты:

• Добавляет DbContextHealthCheck, который вызывает метод EF CoreCanConnectAsync. Имя проверки работоспособности — это имя типа TContext.
• Интегрируется с конечной точкой HTTP /health, которая указывает, что все зарегистрированные проверки состояния должны успешно пройти, чтобы приложение считалось готовым принять трафик.

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

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

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

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

• Microsoft.EntityFrameworkCore.ChangeTracking
• Microsoft.EntityFrameworkCore.Database.Command
• Microsoft.EntityFrameworkCore.Database.Connection
• Microsoft.EntityFrameworkCore.Database.Transaction
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

Трассировка

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

• Npgsql

Метрика

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

• Microsoft.EntityFrameworkCore:

  • ec_Microsoft_EntityFrameworkCore_active_db_contexts
  • ec_Microsoft_EntityFrameworkCore_total_queries
  • ec_Microsoft_EntityFrameworkCore_queries_per_second
  • ec_Microsoft_EntityFrameworkCore_total_save_changes
  • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
  • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
  • ec_Microsoft_Entity_total_execution_strategy_operation_failures
  • ec_Microsoft_E_execution_strategy_operation_failures_per_second
  • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
  • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

• 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 Entity Framework Core интеграция
• интеграции .NET.NET Aspire
• .NET Aspire GitHub репозитория