integração .NET AspirePostgreSQL

2025-06-11

Inclui: —&— Client

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 fornece uma maneira de se conectar a bancos de dados existentes ou criar novas instâncias a partir de com a imagem de contêiner .

Integração de hospedagem

O modelo de integração de hospedagem PostgreSQL classifica vários recursos PostgreSQL como os seguintes tipos.

Para acessar esses tipos e APIs e expressá-los como recursos no projeto app 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 Gerenciar dependências de pacotes em .NET aplicativos.

Adicionar PostgreSQL recurso de servidor

No projeto de host do 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, conforme mostrado no exemplo anterior com a imagem docker.io/library/postgres, ele cria uma nova instância de servidor PostgreSQL no computador local. Uma referência ao servidor e à PostgreSQL instância do banco de dados (a postgresdb variável) é usada para adicionar uma dependência ao ExampleProject.

Ao adicionar um recurso de banco de dados ao modelo de aplicativo, o banco de dados será criado se ele ainda não existir. A criação do banco de dados depende das APIs de evento do host do aplicativo, especificamente ResourceReadyEvent. Em outras palavras, quando o postgres recurso estiver pronto, o evento será gerado e o recurso de banco de dados será criado.

O recurso de servidor PostgreSQL inclui credenciais padrão, consistindo de 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 o ciclo de vida do recurso contêiner.

Dica

Se você preferir se conectar a um servidor PostgreSQL existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referência de recursos existentes.

Adicionar PostgreSQL recurso com scripts de banco de dados

Por padrão, quando você adiciona um PostgresDatabaseResource, ele depende do seguinte script para criar o banco de dados:

CREATE DATABASE "<QUOTED_DATABASE_NAME>"

Para alterar o script padrão, encadeia uma chamada para o WithCreationScript método no construtor de recursos do banco de dados:

var builder = DistributedApplication.CreateBuilder(args);

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

var databaseName = "app_db";
var creationScript = $$"""
    -- Create the database
    CREATE DATABASE {{databaseName}};

    """;

var db = postgres.AddDatabase(databaseName)
                 .WithCreationScript(creationScript);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

O exemplo anterior cria um banco de dados chamado app_db. O script é executado quando o recurso de banco de dados é criado. O script é passado como uma cadeia de caracteres para o WithCreationScript método, que é executado no contexto do PostgreSQL recurso.

Observação

Não há suporte para a conexão a um comando de banco de dados (\c) ao usar o script de criação.

Adicionar PostgreSQL recurso pgAdmin

Ao adicionar recursos ao usando o método , você pode encadear chamadas para para adicionar o contêinerdpage/pgadmin4. Esse contêiner é um cliente multiplataforma para bancos de dados PostgreSQL, que atende 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 de servidor e banco de dados PostgreSQL. O método WithPgAdmin adiciona um contêiner que atende a um painel de administração baseado na Web para bancos de dados PostgreSQL.

Configurar a porta de host pgAdmin

Para configurar a porta de host para o contêiner pgAdmin, chame o método WithHostPort no recurso de servidor PostgreSQL. O exemplo a seguir mostra como configurar a porta 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 de host para o contêiner pgAdmin. Se não for especificado de outra forma, a porta do host é atribuída aleatoriamente.

Adicionar PostgreSQL recurso pgWeb

Ao adicionar PostgreSQL recursos ao builder usando o método AddPostgres, você pode encadear chamadas para WithPgWeb a fim de adicionar o contêiner sosedoff/pgweb. Esse contêiner é um cliente multiplataforma para bancos de dados PostgreSQL, que atende 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 registradas PostgresDatabaseResource são utilizadas para criar um arquivo de configuração por instância, e cada configuração está associada ao diretório de marcadores do contêiner pgweb. Para obter mais informações, consulte documentação do PgWeb: Server indicadores de conexão.

Configurar a porta de host pgWeb

Para configurar a porta de host para o contêiner pgWeb, chame o método WithHostPort no recurso de servidor PostgreSQL. O exemplo a seguir mostra como configurar a porta host para o contêiner pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb(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 de host para o contêiner pgWeb. Se não for especificado de outra forma, a porta do host é atribuída aleatoriamente.

Adicionar PostgreSQL recurso de servidor com volume de dados

Para adicionar um volume de dados ao recurso de servidor PostgreSQL, chame o método WithDataVolume no recurso de 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 persistir 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 preferenciais em vez de montarias de associação, consulte Docker documentos: Volumes.

Importante

Algumas integrações de banco de dados, incluindo a integração .NET AspirePostgreSQL, não podem usar volumes de dados após a implantação no Azure Container Apps ACA. Isso ocorre porque a ACA usa o SMB (Bloco de Mensagens Server ) para conectar contêineres a volumes de dados e alguns sistemas não podem usar essa conexão. Aspire No Painel, um banco de dados afetado por esse problema tem um status de Ativação ou Ativação Com Falha, mas nunca está listado como Em execução.

Você pode resolver o problema usando o Azure serviço gerenciado de banco de dados para PostgreSQL para hospedar o banco de dados implantado em vez de um contêiner na ACA, que é a abordagem recomendada, independentemente desse problema. O código do Host do Aplicativo a seguir mostra como implantar um banco de dados no Azure Banco de Dados para PostgreSQL, mas executá-lo como um contêiner, com um volume de dados, durante o desenvolvimento:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer(container => 
                      {
                        container.WithDataVolume();
                      });

builder.Build().Run();

Adicionar recurso de servidor PostgreSQL com montagem de vínculo de dados

Para adicionar uma montagem de vinculação de dados ao recurso de 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

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

As montagens de ligação de dados dependem do sistema de arquivos da máquina host para persistir os dados do servidor PostgreSQL em reinicializações de contêiner. A montagem de dados bind está montada no caminho C:\PostgreSQL\Data no sistema 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: Associar montagens.

Adicionar recurso de servidor PostgreSQL com a montagem de bind no init

Para adicionar um bind mount de init 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 bind do init depende do sistema de arquivos da máquina host para inicializar o banco de dados do servidor 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 postgres-data . A montagem bind inicial é montada no caminho C:\PostgreSQL\Init no Windows (ou /PostgreSQL/Init no Unix) no computador host, dentro do contêiner de servidor PostgreSQL.

Adicionar PostgreSQL recurso de servidor 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 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 📦 pacote NuGet AspNetCore.HealthChecks.Npgsql .

integração Client

Para começar a integração do cliente , instale o pacote NuGet .Npgsql no projeto que consome o cliente, ou seja, o projeto do aplicativo que utiliza o cliente . A integração do cliente PostgreSQL registra uma instância NpgsqlDataSource com a qual você pode interagir PostgreSQL.

.NET CLI
PackageReference

dotnet add package Aspire.Npgsql

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

Adicionar cliente Npgsql

No arquivo Program.cs do projeto cliente, chame o método de extensão AddNpgsqlDataSource em qualquer IHostApplicationBuilder para registrar um NpgsqlDataSource 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.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 utilizando 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(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

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

Adicionar cliente Npgsql com chave

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

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

Em seguida, você pode recuperar as instâncias de 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 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ê 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 a ConnectionString .

Usar provedores de configuração

A integração .NET AspirePostgreSQL dá suporte a Microsoft.Extensions.Configuration. Ele carrega o NpgsqlSettings a partir de appsettings.json ou outros arquivos de configuração usando a chave Aspire:Npgsql. Exemplo 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 de integração do cliente PostgreSQL completo, consulte 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 desabilitar checagens de saúde.

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

Client checagens de saúde de integração

Por padrão, .NET.NET Aspireas integraçõ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:

Adiciona o NpgSqlHealthCheck, que verifica se os comandos podem ser executados com êxito no banco de dados Postgres subjacente.
Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade registradas devem ser aprovadas para que o aplicativo seja considerado pronto para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire as 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, confira .NET.NET Aspire a 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 Configuração .

Registro

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

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

Rastreamento

A integração .NET AspirePostgreSQL emitirá as seguintes atividades de rastreamento usando 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

Compartilhar via