integração .NET AspirePostgreSQLEntity Framework Core

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

PostgreSQL é um poderoso sistema de banco de dados relacional de objeto de software livre com muitos anos de desenvolvimento ativo que lhe rendeu uma forte reputação de confiabilidade, robustez de recursos e desempenho. A integração .NET AspirePostgreSQLEntity Framework Core fornece uma maneira de se conectar a bancos de dados PostgreSQL existentes ou criar novas instâncias de .NET com a imagem de contêiner docker.io/library/postgres.

Integração de hospedagem

O modelo de integração de hospedagem PostgreSQL modela um PostgreSQLserver como o tipo PostgresServerResource. Para acessar esse tipo e APIs que permitem adicioná-lo ao seu pacote NuGet . Hospedagem. no projeto do host do aplicativo .

dotnet add package Aspire.Hosting.PostgreSQL

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

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicações.

Adicionar PostgreSQLserver recurso

No projeto do host do aplicativo, chame AddPostgres na instância builder para adicionar um recurso PostgreSQLserver e, em seguida, chame AddDatabase na instância postgres para adicionar um recurso de banco de dados, conforme mostrado no exemplo a seguir:

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

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem docker.io/library/postgres, ele cria uma nova instância PostgreSQLserver no computador local. Uma referência ao PostgreSQLserver e à instância do banco de dados PostgreSQL (a variável postgresdb) é usada para adicionar uma dependência ao ExampleProject. O recurso PostgreSQLserver inclui credenciais padrão com um username de "postgres" e password gerados aleatoriamente usando o método CreateDefaultPasswordParameter.

O método WithReference configura uma conexão no ExampleProject denominado "messaging". Para obter mais informações, consulte ciclo de vida do recurso do contêiner.

Adicionar PostgreSQL recurso pgAdmin

Ao adicionar recursos ao utilizando o método , é possível encadear chamadas para a fim de adicionar o contêiner dpage/pgadmin4. Esse contêiner é um client multiplataforma para bancos de dados PostgreSQL, que serve a um painel de administração baseado na Web. Considere o seguinte exemplo:

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

O código anterior adiciona um contêiner com base na imagem docker.io/dpage/pgadmin4. O contêiner é usado para gerenciar os recursos PostgreSQLserver e de banco de dados. O método WithPgAdmin adiciona um contêiner que atende a um painel de administração baseado na Web para bancos de dados PostgreSQL.

Adicionar PostgreSQL recurso pgWeb

Ao adicionar recursos ao com o método , você pode encadear chamadas para para adicionar o contêiner sosedoff/pgweb. Esse contêiner é um client multiplataforma para bancos de dados PostgreSQL, que serve a um painel de administração baseado na Web. Considere o seguinte exemplo:

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

O código anterior adiciona um contêiner com base na imagem docker.io/sosedoff/pgweb. Todas as instâncias de PostgresDatabaseResource cadastradas são usadas para criar um arquivo de configuração para cada instância, e cada configuração está vinculada ao diretório de marcador do contêiner pgweb. Para obter mais informações, consulte PgWeb Docs: Server favoritos de conexão.

Adicionar PostgreSQLserver recurso com volume de dados

Para adicionar um volume de dados ao recurso PostgreSQLserver, chame o método WithDataVolume no recurso PostgreSQLserver:

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

O volume de dados é usado para persistir os dados PostgreSQLserver fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /var/lib/postgresql/data no contêiner PostgreSQLserver e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Adicionar recurso PostgreSQLserver com montagem de vinculação de dados

Para adicionar uma montagem de vinculação de dados ao recurso PostgreSQLserver, chame o método 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...

As montagens de associação de dados dependem do sistema de arquivos do computador host para persistir os dados PostgreSQLserver entre reinicializações de contêiner. A montagem de associação de dados é montada no caminho C:\PostgreSQL\Data no Windows (ou no caminho /PostgreSQL/Data no Unix) na máquina host no contêiner PostgreSQLserver. Para obter mais informações sobre montagens de bind de dados, consulte Docker docs: Montagens de bind.

Adicionar PostgreSQLserver recurso com montagem bind de inicialização

Para adicionar uma montagem de ligação init ao recurso PostgreSQLserver, chame o método 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...

A vinculação de init depende do sistema de arquivos da máquina host para inicializar o banco de dados PostgreSQLserver com a pasta init dos contêineres . Essa pasta é usada para inicialização, executando scripts de shell executáveis ou arquivos de comando .sql após a criação da pasta -data. A montagem de associação de inicialização é montada no caminho C:\PostgreSQL\Init no Windows (ou /PostgreSQL/Init no Unix) no computador host no contêiner PostgreSQLserver.

Adicionar PostgreSQLserver recurso com parâmetros

Quando você quiser fornecer explicitamente o nome de usuário e a senha usados pela imagem de contêiner, você pode fornecer essas credenciais como parâmetros. Considere o seguinte exemplo alternativo:

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

Para obter mais informações sobre como fornecer parâmetros, consulte Parâmetros externos.

Verificações de integridade de integração de hospedagem

A integração de hospedagem PostgreSQL adiciona automaticamente uma verificação de integridade para o recurso de PostgreSQLserver. A checagem de saúde assegura que o PostgreSQLserver está em execução e que uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do pacote NuGet 📦 AspNetCore.HealthChecks.Npgsql.

integração Client

Para começar a usar a integração .NET AspirePostgreSQLEntity Framework Coreclient, instale o pacote NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL no projeto que está consumindo client, ou seja, o projeto do aplicativo que utiliza o PostgreSQLclient. A integração .NET AspirePostgreSQLEntity Framework Coreclient registra as instâncias de subclasse de DbContext desejadas que você pode usar para interagir com PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

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

Adicionar contexto de banco de dados Npgsql

No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddNpgsqlDbContext em qualquer IHostApplicationBuilder para registrar sua subclasse DbContext para uso através 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");

Depois de adicionar YourDbContext ao construtor, você pode obter a instância de YourDbContext usando a injeção de dependência. 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.

Adicionar contexto de banco de dados Npgsql com enriquecimento

Para enriquecer o DbContext com serviços adicionais, como repetições automáticas, verificações de integridade, registro em log e telemetria, chame o método EnrichNpgsqlDbContext:

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    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",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true
        }
      }
    }
  }
}

Para o esquema completo de integração PostgreSQLEntity Framework CoreclientJSON, 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 diretamente, 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, poderá usar o nome da seção de configuração $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". A configuração de json seria semelhante a:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DbContextPooling": true,
          "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 carregaria as configurações da seção Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Verificações de saúde

Por padrão, as integrações .NET.NET Aspire habilitam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

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

Azure PostgreSQL integração de hospedagem

Para desplegar seus recursos PostgreSQL em Azure, instale o pacote NuGet 📦Aspire.Hospedagem.Azure.PostgreSQL:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

Adicionar AzurePostgreSQLserver recurso

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 server PostgresSQL para ser implantado como um Flexível AzurePostgresServer.

Adicionar Npgsql autenticado Azureclient

Por padrão, quando você chama AddAzurePostgresFlexibleServer em sua integração de hospedagem PostgreSQL, ele configura o pacote NuGet 📦Azurede identidade para habilitar a autenticação.

dotnet add package Azure.Identity

<PackageReference Include="Azure.Identity"
                  Version="*" />

A conexão PostgreSQL pode ser consumida usando a integração client 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 snippet de código anterior demonstra como usar a classe DefaultAzureCredential do pacote Azure.Identity para autenticar com da ID do Microsoft Entra 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

• Azure Banco de Dados para documentação PostgreSQL
• .NET .NET Aspire integrações
• .NET Aspire GitHub repo