Partilhar via

.NET Aspire PostgreSQL Entity Framework Core integração

  • Artigo

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

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

Integração de hospedagem

A integração de hospedagem PostgreSQL modela um PostgreSQLserver como o tipo PostgresServerResource. Para aceder a este tipo e às APIs que lhe permitem adicioná-lo ao seu 📦Aspire.Hospedagem.PostgreSQL pacote NuGet no projeto do host da aplicação .

dotnet add package Aspire.Hosting.PostgreSQL

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

Adicionar PostgreSQLserver recurso

Em seu projeto de host de aplicativo, chame AddPostgres na instância builder para adicionar um recurso de 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, como mostrado no exemplo anterior com a imagem docker.io/library/postgres, ele cria uma nova instância de PostgreSQLserver em sua máquina local. Uma referência ao seu PostgreSQLserver e sua instância de banco de dados PostgreSQL (a variável postgresdb) são usadas para adicionar uma dependência ao ExampleProject. O recurso PostgreSQLserver inclui credenciais padrão com uma username de "postgres" e password gerados aleatoriamente usando o método CreateDefaultPasswordParameter.

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

Dica

Se preferir conectar-se a um PostgreSQLserverexistente, ligue para AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a recursos existentes.

Adicionar PostgreSQL recurso pgAdmin

Ao adicionar recursos de PostgreSQL ao builder com o método AddPostgres, pode-se encadear chamadas para WithPgAdmin para adicionar o contentor dpage/pgadmin4 . Esse contêiner é um client multiplataforma para bancos de dados PostgreSQL, que serve 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 contentor é utilizado para gerir os recursos de PostgreSQL,server e de base de dados. O método WithPgAdmin adiciona um contêiner que serve um painel de administração baseado na Web para bancos de dados PostgreSQL.

Adicionar PostgreSQL recurso pgWeb

Ao adicionar recursos de 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 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 registradas são usadas para criar um arquivo de configuração por instância e cada configuração é vinculada ao diretório de marcadores de contêiner pgweb. Para obter mais informações, consulte documentos PgWeb: Server marcadores de conexão.

Adicionar recurso PostgreSQLserver 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 do 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 preferidos em relação a montagens bind , consulte a documentação Docker: Volumes.

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

Para adicionar uma montagem de associaçã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...

Importante

Os suportes de ligação de de dados têm funcionalidade limitada em comparação com volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos da máquina host para manter os dados PostgreSQLserver nas reinicializações do contêiner. A montagem de vinculação de dados está montada no caminho C:\PostgreSQL\Data no Windows (ou /PostgreSQL/Data no Unix) na máquina anfitriã no contentor PostgreSQLserver. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

Adicionar recurso PostgreSQLserver com inicialização de montagem vinculada

Para adicionar um bind mount 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 montagem de ligação 'init' depende do sistema de arquivos da máquina host para inicializar o banco de dados PostgreSQLserver com a pasta 'init' dos contêineres . Esta pasta é usada para inicialização, para executar quaisquer scripts executáveis de shell ou ficheiros de comando .sql depois de a pasta postgres-data ser criada. A montagem de ligação de inicialização é montada no caminho C:\PostgreSQL\Init no Windows (ou /PostgreSQL/Init no Unix) na máquina host no contêiner PostgreSQLserver.

Adicionar PostgreSQLserver recurso com parâmetros

Quando quiser fornecer explicitamente o nome de usuário e a senha usados pela imagem do contêiner, você poderá 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 da integração de hospedagem

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

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

Client integração

Para começar com a integração .NET AspirePostgreSQLEntity Framework Coreclient, instale o 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL pacote NuGet no projeto que consome client, isto é, o projeto do aplicativo que utiliza o PostgreSQLclient. A integração de .NET AspirePostgreSQLEntity Framework Coreclient regista as instâncias de subclasse desejadas de DbContext que podem ser usadas para interagir com PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Adicionar contexto de banco de dados Npgsql

No arquivo de Program.cs do seu projeto que consome client, chame o método de extensão AddNpgsqlDbContext em qualquer IHostApplicationBuilder para registar a 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 PostgreSQLserver no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar PostgreSQLserver recurso.

Depois de adicionar YourDbContext ao construtor, você pode obter a instância YourDbContext usando a injeção de dependência. Por exemplo, para recuperar seu objeto de 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 mais informações sobre a 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 e opções de configuração 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 ConnectionStrings:

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

O EnrichNpgsqlDbContext não usará a seção de configuração 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 suporta Microsoft.Extensions.Configuration. Ele carrega o NpgsqlEntityFrameworkCorePostgreSQLSettings de arquivos de configuração, como appsettings.json, usando a chave Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Se você configurou suas configurações na seção Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, você pode 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 em linha

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 quiseres registar mais de um DbContext com configuração diferente, podes usar o nome da secçã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>",
          "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>();

Controlos sanitários

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 das integrações.

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

  • Adiciona o DbContextHealthCheck, que chama o método CanConnectAsync de EF Core. O nome da verificação de saúde é o nome do tipo de TContext.
  • Integra-se com o ponto de extremidade HTTP /health, que especifica que todas as verificações de integridade registadas devem ser aprovadas para que a aplicação seja considerada pronta para aceitar tráfego

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na secção de configuração .

Registo

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

Rastreio

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 implantar os seus recursos de PostgreSQL no Azure, instale o 📦Aspire.Hosting.Azure.PostgreSQL pacote NuGet:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Adicionar AzurePostgreSQLserver recurso

Depois de instalar a integração de hospedagem .NET AspireAzurePostgreSQL, chame o método de extensão AddAzurePostgresFlexibleServer em seu projeto de host de 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 PostgresSQL server a ser implantado como um AzurePostgres flexível Server.

Importante

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

Adicionar Azureclient Npgsql autenticado

Por padrão, quando tu chamas AddAzurePostgresFlexibleServer na tua integração de alojamento PostgreSQL, ele configura o pacote NuGet 📦Azure.Identidade para habilitar a autenticação:

dotnet add package Azure.Identity

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 trecho de código anterior demonstra como usar a classe DefaultAzureCredential do pacote Azure.Identity para autenticar com de 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 da cadeia de conexão.

Ver também