Compartilhar via

integração .NET AspireAzurePostgreSQLEntity Framework Core

  • Artigo

Inclui: integração de hospedagem e Client integração

banco de dados Azure para PostgreSQL— o Server flexível é um serviço de banco de dados relacional baseado no mecanismo de banco de dados Postgres de software livre. É um banco de dados como serviço totalmente gerenciado que pode lidar com cargas de trabalho críticas com desempenho previsível, segurança, alta disponibilidade e escalabilidade dinâmica. A integração .NET AspireAzurePostgreSQL fornece uma maneira de se conectar a bancos de dados AzurePostgreSQL existentes ou criar novas instâncias a partir de .NET com a imagem de contêiner docker.io/library/postgres.

Integração de hospedagem

.NET Aspire Azure PostgreSQL A integração de hospedagem modela um servidor flexível e banco de dados como os tipos AzurePostgresFlexibleServerResource e AzurePostgresFlexibleServerDatabaseResource. Outros tipos que estão inerentemente disponíveis na integração de hospedagem são representados nos seguintes recursos:

Para acessar esses tipos e APIs para expressá-los como recursos em seu projeto de aplicativo host , instale o pacote NuGet 📦Aspire.Hosting.Azure.PostgreSQL:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Para obter mais informações, consulte dotnet add package.

A integração de hospedagem AzurePostgreSQL depende do pacote NuGet 📦Aspire.Hosting.PostgreSQL, estendendo-o para suportar Azure. Tudo o que você pode fazer com a integração .NET AspirePostgreSQL e a integração .NET AspirePostgreSQLEntity Framework Core você também pode fazer com essa integração.

Adicionar AzurePostgreSQL recurso de servidor

Depois de instalar a integração de hospedagem .NET AspireAzurePostgreSQL, chame o método de extensão AddAzurePostgresFlexibleServer no projeto de host do aplicativo:

var builder = DistributedApplication.CreateBuilder(args);

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

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

A chamada anterior para AddAzurePostgresFlexibleServer configura o recurso de servidor PostgreSQL a ser implantado como um AzurePostgres Flexível Server.

Importante

Por padrão, AddAzurePostgresFlexibleServer configura a autenticação Microsoft Entra ID. Isso requer alterações em aplicativos que precisam se conectar a esses recursos. Para obter mais informações, consulte a integração Client.

Dica

Quando você chama AddAzurePostgresFlexibleServer, ele chama implicitamente AddAzureProvisioning— o que adiciona suporte para gerar recursos Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração.

Provisionamento gerado no Bicep

Caso você seja novo no Bicep, saiba que é uma linguagem de domínio específico para definir recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, pois as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é exibido juntamente ao arquivo de manifesto. Quando você adiciona um recurso AzurePostgreSQL, o seguinte Bicep é gerado:

@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}'

O Bicep anterior é um módulo que provisiona um servidor flexível AzurePostgreSQL com os seguintes padrões:

  • authConfig: a configuração de autenticação do servidor PostgreSQL. O padrão é ActiveDirectoryAuth habilitado e PasswordAuth desabilitado.
  • availabilityZone: a zona de disponibilidade do servidor PostgreSQL. O padrão é 1.
  • backup: a configuração de backup do servidor PostgreSQL. O padrão consiste em BackupRetentionDays ser definido como 7 e GeoRedundantBackup como Disabled.
  • highAvailability: a configuração de alta disponibilidade do servidor PostgreSQL. O padrão é Disabled.
  • storage: a configuração de armazenamento do servidor PostgreSQL. O padrão é StorageSizeGB, definido para 32.
  • version: a versão do servidor PostgreSQL. O padrão é 16.
  • sku: O código SKU do servidor PostgreSQL. O padrão é Standard_B1ms.
  • tags: os tags do servidor PostgreSQL. O padrão é aspire-resource-name definido como o nome do recurso Aspire, nesse caso postgres-flexible.

Além do servidor flexível PostgreSQL, ele também provisiona uma regra de Firewall Azure para permitir o acesso a todos os endereços IP Azure. Por fim, um administrador é criado para o servidor PostgreSQL e a cadeia de conexão é gerada como uma variável de saída. O Bicep gerado é um ponto de partida e pode ser personalizado para atender aos seus requisitos específicos.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite personalizar o Bicep gerado ao oferecer uma API fluente para configurar os recursos do Azure usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o kind, consistencyPolicy, locationse muito mais. O exemplo a seguir demonstra como personalizar o recurso de servidor PostgreSQL:

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");
    });

O código anterior:

Há muitas outras opções de configuração disponíveis para personalizar o PostgreSQL recurso de servidor flexível. Para obter mais informações, consulte Azure.Provisioning.PostgreSql e Azure. Customização de provisionamento.

Conectar-se a um servidor flexível AzurePostgreSQL existente

Você pode ter um servidor AzurePostgreSQL flexível existente ao qual deseja se conectar. Em vez de representar um novo recurso de servidor AzurePostgreSQL flexível, você pode adicionar uma cadeia de conexão ao host do aplicativo. Para adicionar uma conexão a um servidor flexível AzurePostgreSQL existente, chame o método 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...

Nota

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Em .NET.NET Aspire nomenclatura, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário, na seção ConnectionStrings. O host do aplicativo injeta essa cadeia de conexão como uma variável de ambiente em todos os recursos dependentes, por exemplo:

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

O recurso dependente pode acessar a cadeia de conexão injetada chamando o método GetConnectionString e passando o nome da conexão como o parâmetro, nesse caso "postgres". A API GetConnectionString é uma abreviação de IConfiguration.GetSection("ConnectionStrings")[name].

Executar AzurePostgreSQL recurso como um contêiner

A AzurePostgreSQL integração de hospedagem dá suporte à execução do servidor PostgreSQL como um contêiner local. Isso é benéfico para situações em que você deseja executar o servidor PostgreSQL localmente para fins de desenvolvimento e teste, evitando a necessidade de provisionar um recurso Azure ou conectar-se a um servidor AzurePostgreSQL existente.

Para executar o servidor PostgreSQL como um contêiner, chame o método 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);

O código anterior configura um recurso de Azure Flexível PostgreSQLServer para ser executado localmente em um contêiner.

Dica

O método RunAsContainer é útil para desenvolvimento e teste locais. A API expõe um delegado opcional que permite personalizar a configuração de PostgresServerResource subjacente. Por exemplo, você pode adicionar pgAdmin e pgWeb, adicionar um volume de dados ou uma montagem de associação de dados e adicionar uma montagem de associação de init. Para obter mais informações, consulte a seção de integração de hospedagem .NET AspirePostgreSQL.

Configurar o servidor AzurePostgreSQL para usar a autenticação de senha

Por padrão, o servidor AzurePostgreSQL está configurado para usar a autenticação da ID do Microsoft Entra . Se você quiser usar a autenticação de senha, poderá configurar o servidor para usar a autenticação de senha chamando o método 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);

O código anterior configura o servidor AzurePostgreSQL para usar a autenticação de senha. Os parâmetros username e password são adicionados ao host do aplicativo como parâmetros e o método WithPasswordAuthentication é chamado para configurar o servidor AzurePostgreSQL para usar a autenticação de senha. Para obter mais informações, consulte Parâmetros externos.

integração Client

Para começar a usar a integração do cliente .NET AspirePostgreSQLEntity Framework Core, instale o pacote NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL no projeto que consome o cliente, ou seja, o projeto do aplicativo que usa o cliente PostgreSQL. A integração do cliente .NET AspirePostgreSQLEntity Framework Core registra suas instâncias de subclasse desejadas de DbContext que você pode usar para interagir com PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Adicionar contexto de banco de dados Npgsql

No arquivo Program.cs do projeto que utiliza o cliente, chame o método de extensão AddNpgsqlDbContext em qualquer IHostApplicationBuilder para registrar sua subclasse DbContext para uso por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

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

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso de servidor PostgreSQL no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar PostgreSQL recurso do servidor.

Depois de adicionar YourDbContext ao construtor, você pode usar a injeção de dependência para obter a instância YourDbContext. Por exemplo, para recuperar o objeto da fonte de dados de um serviço de exemplo, defina-o como um parâmetro de construtor e verifique se a classe ExampleService está registrada com o contêiner de injeção de dependência:

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

Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Enriquecer o contexto de um banco de dados utilizando Npgsql

Você pode preferir usar o método Entity Framework padrão para obter um contexto de banco de dados e adicioná-lo ao contêiner de injeção de dependência:

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));

Nota

O nome da cadeia de conexão que você passa para o método GetConnectionString deve corresponder ao nome usado ao adicionar o recurso de servidor PostgreSQL no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar PostgreSQL recurso do servidor.

Você tem mais flexibilidade ao criar o contexto do banco de dados dessa maneira, por exemplo:

  • Você pode reutilizar o código de configuração existente para o contexto do banco de dados sem reescrevê-lo para .NET.NET Aspire.
  • Você pode usar Entity Framework Core interceptores para modificar operações de banco de dados.
  • Você pode optar por não usar a agregação de contexto Entity Framework Core, o que pode ter um desempenho melhor em algumas circunstâncias.

Se você usar esse método, poderá aprimorar o contexto do banco de dados com repetições de estilo .NET.NET Aspire, verificações de integridade, registro em log e recursos de telemetria chamando o método EnrichNpgsqlDbContext:

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

O parâmetro settings é uma instância da classe NpgsqlEntityFrameworkCorePostgreSQLSettings.

Configuração

A integração .NET AspirePostgreSQLEntity Framework Core fornece várias abordagens de configuração e opções para atender aos requisitos e convenções do seu projeto.

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você fornece o nome da cadeia de conexão ao chamar o método AddNpgsqlDbContext:

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

A cadeia de conexão é recuperada da seção de configuração do ConnectionStrings:

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

O EnrichNpgsqlDbContext não usará a seção de configuração de ConnectionStrings, pois espera que um DbContext seja registrado no ponto em que é chamado.

Para obter mais informações, consulte o ConnectionString.

Usar provedores de configuração

A integração .NET AspirePostgreSQLEntity Framework Core dá suporte a Microsoft.Extensions.Configuration. Ele carrega o NpgsqlEntityFrameworkCorePostgreSQLSettings de arquivos de configuração, como appsettings.json usando a chave Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Se você tiver configurado suas configurações na seção Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, poderá simplesmente chamar o método sem passar nenhum parâmetro.

O exemplo a seguir mostra um arquivo appsettings.json que configura algumas das opções disponíveis:

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

Para obter o esquema PostgreSQL de integração completa do cliente Entity Framework CoreJSON, consulte Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Usar delegados embutidos

Você também pode passar o delegado Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> para configurar algumas ou todas as opções em linha, por exemplo, para definir o ConnectionString.

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

Configurar várias classes DbContext

Se você quiser registrar mais de uma DbContext com configuração diferente, você pode usar o nome da seção de configuração $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". A configuração json seria semelhante a:

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

Em seguida, chamar o método AddNpgsqlDbContext com o parâmetro de tipo AnotherDbContext irá carregar as configurações da seção Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Client checagens de saúde de integração

Por padrão, .NET.NET Aspireintegrações de cliente têm verificações de integridade habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também habilitam endpoints para verificação de saúde. Para obter mais informações, consulte:

Por padrão, as integrações de .NET AspirePostgreSQLEntity Framework Core manipulam o seguinte:

  • Adiciona o DbContextHealthCheck, que chama o método CanConnectAsync do EF Core. O nome da verificação de saúde é o nome do tipo TContext.
  • Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade registradas devem passar para que o aplicativo seja considerado pronto para aceitar o tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração .NET AspirePostgreSQLEntity Framework Core usa as seguintes categorias de Log:

  • 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

Rastreamento

A integração .NET AspirePostgreSQLEntity Framework Core emitirá as seguintes atividades de rastreamento usando OpenTelemetry:

  • Npgsql

Métricas

A integração .NET AspirePostgreSQLEntity Framework Core emitirá as seguintes métricas usando 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

Adicionar cliente Npgsql autenticado Azure

Por padrão, quando você chama AddAzurePostgresFlexibleServer em sua integração de hospedagem PostgreSQL, é necessário o pacote NuGet 📦Azure.Identity para habilitar a autenticação.

dotnet add package Azure.Identity

A conexão PostgreSQL pode ser consumida usando a integração do cliente e 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));
});

O trecho de código anterior demonstra como usar a classe DefaultAzureCredential do pacote Azure.Identity para autenticar com o Microsoft Entra ID e recuperar um token para se conectar ao banco de dados PostgreSQL. O método UsePeriodicPasswordProvider é usado para fornecer o token ao construtor de cadeias de conexão.

Consulte também