.NET Aspire PostgreSQL integração

Artigo
01/31/2025

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 .NET AspirePostgreSQL 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 vários recursos PostgreSQL como os seguintes tipos.

Para aceder a esses tipos e APIs para os expressar como recursos no seu projeto de aplicativo host , instale o pacote NuGet 📦Aspire.Hosting.PostgreSQL:

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.PostgreSQL

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

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

Adicionar PostgreSQL recurso do servidor

Em seu projeto de host de aplicativo, chame AddPostgres na instância builder para adicionar um recurso de servidor PostgreSQL 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 do servidor PostgreSQL em sua máquina local. Uma referência ao servidor PostgreSQL e à instância do banco de dados PostgreSQL (a variável postgresdb) são usadas para adicionar uma dependência ao ExampleProject. O recurso de servidor PostgreSQL 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 você preferir se conectar a um servidor PostgreSQL existente, ligue para AddConnectionString em vez disso. Para mais informações, consulte Recursos existentes de referência.

Adicionar PostgreSQL recurso pgAdmin

Ao adicionar recursos de ao com o método , você pode encadear chamadas para para adicionar o contêiner dpage/pgadmin4 . Esse contêiner é um cliente 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 contêiner é usado para gerenciar o servidor PostgreSQL e os recursos do banco 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.

Configurar a porta de host pgAdmin

Para configurar a porta do host para o contêiner pgAdmin, chame o método WithHostPort no recurso do servidor PostgreSQL. O exemplo a seguir mostra como configurar a porta do host para o contêiner 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...

O código anterior adiciona e configura a porta do host para o contêiner pgAdmin. Caso contrário, a porta do host é atribuída aleatoriamente.

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 cliente 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 os documentos PgWeb : marcadores de conexão Server.

Configurar a porta de host pgWeb

Para configurar a porta do host para o contêiner pgWeb, chame o método WithHostPort no recurso do servidor PostgreSQL. O exemplo a seguir mostra como configurar a porta do host para o contêiner 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...

O código anterior adiciona e configura a porta do host para o contêiner pgWeb. Caso contrário, a porta do host é atribuída aleatoriamente.

Adicionar o recurso do servidor PostgreSQL com volume de dados

Para adicionar um volume de dados ao recurso do servidor PostgreSQL, chame o método WithDataVolume no recurso do servidor 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...

O volume de dados é usado para manter os dados do servidor PostgreSQL fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /var/lib/postgresql/data no contêiner do servidor PostgreSQL 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 de ligação , consulte Docker docs: Volumes.

Adicionar PostgreSQL recurso de servidor com montagem de associação de dados

Para adicionar uma montagem de ligação de dados ao recurso do servidor PostgreSQL, 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 vínculo de dados dependem do sistema de arquivos da máquina host para manter os dados do servidor PostgreSQL durante reinicializações do contêiner. A montagem de associação de dados é montada no C:\PostgreSQL\Data no caminho do Windows (ou /PostgreSQL/Data no Unix) na máquina host no contêiner do servidor PostgreSQL. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

Adicionar o recurso do servidor PostgreSQL com a montagem de ligação init bind

Para adicionar uma montagem de ligação de arranque ao recurso de servidor PostgreSQL, 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 do servidor PostgreSQL com os contêineres pasta init. Esta pasta é usada para inicialização, executando quaisquer scripts shell executáveis ou arquivos de comando .sql após a pasta postgres-data ser criada. A montagem inicial de ligação é montada no caminho C:\PostgreSQL\Init no Windows (ou /PostgreSQL/Init no Unix) na máquina host, no contentor do servidor PostgreSQL.

Adicionar PostgreSQL recurso do servidor 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 de servidor PostgreSQL. A verificação de integridade verifica se o servidor PostgreSQL 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.

integração Client

Para começar com a integração do cliente .NET AspirePostgreSQL, instale o 📦Aspire.Npgsql pacote NuGet no projeto que consome o cliente, ou seja, o projeto do aplicativo que utiliza o cliente PostgreSQL. A integração do cliente PostgreSQL regista uma instância de NpgsqlDataSource que pode ser utilizada para interagir com PostgreSQL.

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql

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

Adicionar cliente Npgsql

No ficheiro Program.cs do seu projeto cliente, chame o método de extensão AddNpgsqlDataSource em qualquer IHostApplicationBuilder para registar um NpgsqlDataSource para uso através do contêiner de injeção de dependências. O método usa um parâmetro de nome de conexão.

builder.AddNpgsqlDataSource(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 de servidor.

Depois de adicionar NpgsqlDataSource ao construtor, você pode obter a instância NpgsqlDataSource 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(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

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

Adicionar cliente Npgsql com chave

Pode haver situações em que você queira registrar várias instâncias de NpgsqlDataSource com nomes de conexão diferentes. Para registrar clientes Npgsql com chave, chame o método AddKeyedNpgsqlDataSource:

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

Em seguida, você pode recuperar as instâncias NpgsqlDataSource usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

Para obter mais informações sobre serviços com chave, consulte .NET injeção de dependência: Serviços com chave.

Configuração

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

Usar uma cadeia de conexão

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

builder.AddNpgsqlDataSource("postgresdb");

Em seguida, a cadeia de conexão será recuperada da seção de configuração ConnectionStrings:

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

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

Usar provedores de configuração

A integração .NET AspirePostgreSQL suporta Microsoft.Extensions.Configuration. Carrega o NpgsqlSettings a partir de appsettings.json ou outros ficheiros de configuração usando a chave Aspire:Npgsql. Exemplo de appsettings.json que configura algumas das opções:

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

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

Para obter o esquema completo de integração do cliente PostgreSQLJSON, consulte Aspire. Npgsql/ConfigurationSchema.json.

Usar delegados embutidos

Você também pode passar o delegado Action<NpgsqlSettings> configureSettings para configurar algumas ou todas as opções diretamente, por exemplo, para desativar as verificações de saúde:

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

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.

Adiciona o NpgSqlHealthCheck, que verifica se os comandos podem ser executados com êxito no banco de dados Postgres subjacente.
Integra-se com o ponto de extremidade HTTP /health, onde é especificado que todas as verificações de integridade registadas devem passar para que o aplicativo seja considerado pronto para receber tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as funções de registo, rastreamento e métricas, 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 utilizando as técnicas apresentadas na seção Configuração.

Registo

A integração .NET AspirePostgreSQL usa as seguintes categorias de log:

Npgsql.Connection
Npgsql.Command
Npgsql.Transaction
Npgsql.Copy
Npgsql.Replication
Npgsql.Exception

Rastreio

A integração .NET AspirePostgreSQL emitirá as seguintes atividades de rastreio utilizando OpenTelemetry:

Npgsql

Métricas

A integração .NET AspirePostgreSQL emitirá as seguintes métricas usando OpenTelemetry:

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

Partilhar via