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

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

  • Статья

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

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

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

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

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

Интеграция хостинга AzurePostgreSQL основывается на пакете NuGet 📦Aspire.Hosting.PostgreSQL, расширяя его для поддержки 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 во время запуска приложения. Приложение должно настроить соответствующую подписку и местоположение. Для получения дополнительной информации см. раздел Локальное развертывание: Конфигурация.

Генерированное предоставление Bicep

Если вы не знакомы с Bicep, это специализированный язык для определения ресурсов Azure. При использовании .NET.NET Aspireвам не нужно писать Bicep вручную, так как API подготовки генерируют Bicep для вас. При публикации приложения созданный Bicep выводится вместе с файлом манифеста. При добавлении ресурса AzurePostgreSQL создается следующий Bicep:


переключение AzurePostgreSQL бицепс. 

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalType string

param principalName string

resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = {
  name: take('postgresflexible-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    authConfig: {
      activeDirectoryAuth: 'Enabled'
      passwordAuth: 'Disabled'
    }
    availabilityZone: '1'
    backup: {
      backupRetentionDays: 7
      geoRedundantBackup: 'Disabled'
    }
    highAvailability: {
      mode: 'Disabled'
    }
    storage: {
      storageSizeGB: 32
    }
    version: '16'
  }
  sku: {
    name: 'Standard_B1ms'
    tier: 'Burstable'
  }
  tags: {
    'aspire-resource-name': 'postgres-flexible'
  }
}

resource postgreSqlFirewallRule_AllowAllAzureIps 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2024-08-01' = {
  name: 'AllowAllAzureIps'
  properties: {
    endIpAddress: '0.0.0.0'
    startIpAddress: '0.0.0.0'
  }
  parent: postgres_flexible
}

resource postgres_flexible_admin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01' = {
  name: principalId
  properties: {
    principalName: principalName
    principalType: principalType
  }
  parent: postgres_flexible
  dependsOn: [
    postgres_flexible
    postgreSqlFirewallRule_AllowAllAzureIps
  ]
}

output connectionString string = 'Host=${postgres_flexible.properties.fullyQualifiedDomainName};Username=${principalName}'

Предыдущая версия Bicep — это модуль, который подготавливает гибкий сервер AzurePostgreSQL со следующими значениями по умолчанию:

  • authConfig: конфигурация проверки подлинности сервера PostgreSQL. По умолчанию ActiveDirectoryAuth включено, а PasswordAuth отключено.
  • availabilityZone: зона доступности сервера PostgreSQL. Значение по умолчанию — 1.
  • backup: конфигурация резервного копирования сервера PostgreSQL. По умолчанию BackupRetentionDays установлено на 7, а GeoRedundantBackup — на Disabled.
  • highAvailability. Конфигурация высокого уровня доступности сервера PostgreSQL. Значение по умолчанию — Disabled.
  • storage: конфигурация хранилища сервера PostgreSQL. По умолчанию StorageSizeGB задано значение 32.
  • version: версия сервера PostgreSQL. Значение по умолчанию — 16.
  • sku: номер SKU сервера PostgreSQL. Значение по умолчанию — Standard_B1ms.
  • tags: метки сервера PostgreSQL. По умолчанию aspire-resource-name установлено на имя ресурса Aspire, в данном случае postgres-flexible.

Помимо гибкого сервера PostgreSQL, он также подготавливает правило брандмауэра Azure для разрешения всех Azure IP-адресов. Наконец, администратор создается для сервера PostgreSQL, а строка подключения выводится в виде выходной переменной. Созданный Bicep является отправной точкой и может быть настроен в соответствии с вашими конкретными требованиями.

Настройка инфраструктуры подготовки

Все .NET AspireAzure ресурсы — это подклассы типа AzureProvisioningResource. Этот тип позволяет конфигурировать созданный Bicep, предоставляя гибкий API для настройки ресурсов Azure с помощью API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Например, можно настроить kind, consistencyPolicy, locationsи многое другое. В следующем примере показано, как настроить ресурс AzureAzure Cosmos DB:

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var flexibleServer = infra.GetProvisionableResources()
                                  .OfType<PostgreSqlFlexibleServer>()
                                  .Single();

        flexibleServer.Sku = new PostgreSqlFlexibleServerSku
        {
            Tier = PostgreSqlFlexibleServerSkuTier.Burstable,
        };
        flexibleServer.HighAvailability = new PostgreSqlFlexibleServerHighAvailability
        {
            Mode = PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant,
            StandbyAvailabilityZone = "2",
        };
        flexibleServer.Tags.Add("ExampleKey", "Example value");
    });

Предыдущий код:

Существует множество дополнительных параметров конфигурации для настройки PostgreSQL гибкого ресурса сервера. Дополнительные сведения см. в Azure.Provisioning.PostgreSql. Дополнительные сведения см. в разделе Azure. Адаптация настройки.

Подключение к существующему гибкому серверу AzurePostgreSQL

У вас может быть существующий AzurePostgreSQL гибкий сервер, к которому требуется подключиться. Вместо того чтобы представлять новый AzurePostgreSQL гибкий ресурс сервера, можно добавить строку подключения к хосту приложения. Чтобы добавить подключение к существующему гибкому серверу AzurePostgreSQL, вызовите метод AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(postgres);

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

Заметка

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

Строка подключения настраивается в конфигурации узла приложения, как правило, в разделе Секреты пользователейв разделе ConnectionStrings. Хост приложения внедряет строку подключения в качестве переменной среды во все зависимые ресурсы, например:

{
    "ConnectionStrings": {
        "postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
    }
}

Зависимый ресурс может получить доступ к внедренной строке подключения, вызвав метод GetConnectionString и передав имя подключения в качестве параметра, в этом случае "postgres". API GetConnectionString является сокращением для IConfiguration.GetSection("ConnectionStrings")[name].

Запуск ресурса AzurePostgreSQL в качестве контейнера

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

Чтобы запустить сервер PostgreSQL в качестве контейнера, вызовите метод RunAsContainer:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer();

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

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

Приведенный выше код настраивает гибкий ресурс AzurePostgreSQLServer для локального выполнения в контейнере.

Совет

Метод RunAsContainer полезен для локальной разработки и тестирования. API предоставляет необязательный делегат, позволяющий настроить базовую конфигурацию PostgresServerResource, например добавить pgAdmin, pgWeb, добавить том данных или подключение привязки данных и добавить подключение привязки init. Для получения дополнительной информации см. раздел .NET AspirePostgreSQL о хостинге и интеграции.

Настройка сервера AzurePostgreSQL для использования проверки подлинности паролей

По умолчанию сервер AzurePostgreSQL настроен для использования проверки подлинности Microsoft Entra ID. Если вы хотите использовать проверку подлинности паролей, можно настроить сервер для использования проверки подлинности паролей, вызвав метод WithPasswordAuthentication:

var builder = DistributedApplication.CreateBuilder(args);

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

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .WithPasswordAuthentication(username, password);

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

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

Приведенный выше код настраивает сервер AzurePostgreSQL для использования проверки подлинности паролей. Параметры username и password добавляются в узел приложения в качестве параметров, а метод WithPasswordAuthentication вызывается для настройки сервера AzurePostgreSQL для использования проверки подлинности паролей. Дополнительные сведения см. в разделе Внешние параметры.

интеграция Client

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

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Добавьте контекст базы данных 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, который вызывает метод CanConnectAsync у EF Core. Название проверки состояния — это название типа 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

Добавить аутентифицированного клиента Azure Npgsql

По умолчанию, когда вы вызываете AddAzurePostgresFlexibleServer в интеграции PostgreSQL хостинга, требуется пакет NuGet 📦Azure.Identity для включения аутентификации.

dotnet add package Azure.Identity

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

builder.AddNpgsqlDbContext<YourDbContext>(
    "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 используется для предоставления токена генератору строк подключения.

См. также