integração .NET AspirePostgreSQL
Inclui:
integração de hospedagem e integração 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 .NET AspirePostgreSQL 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 PostgreSQL modelo de integração de hospedagem PostgreSQLserver como o tipo PostgresServerResource. Para acessar esse tipo e APIs que permitem adicioná-lo ao seu pacote NuGet de hospedagem em 📦AspirePostgreSQL no projeto de host do aplicativo .
- .NET CLI
-
PackageReference
dotnet add package Aspire.Hosting.PostgreSQL
Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicativos.
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) são usadas 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.
Dica
Se você preferir se conectar a um PostgreSQLserverexistente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.
Adicionar PostgreSQL recurso pgAdmin
Ao adicionar recursos
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 PostgreSQLserver e os recursos 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 PostgreSQL ao builder com o método AddPostgres, você pode encadear chamadas para WithPgWeb para adicionar o contêiner sosedoff/pgweb. Esse contêiner é um client multiplataforma para bancos de dados PostgreSQL, que fornece um painel de administração baseado em 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 config está vinculada ao diretório pgweb de marcadores do contêiner. Para obter mais informações, consulte documentos pgWeb: Server indicadores 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 o recurso PostgreSQLserver com montagem de vínculo 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 de dados associam montagens 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 de vínculo permitem acesso direto e modificação de arquivos no sistema host, sendo ideal para desenvolvimento e testes em que alterações em tempo real são necessárias.
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 no contêiner PostgreSQLserver é montada no diretório C:\PostgreSQL\Data no Windows (ou /PostgreSQL/Data no Unix) no computador host. Para obter mais informações sobre pontos de montagem de dados, consulte os documentos Docker: Montagens de associação.
Adicionar recurso PostgreSQLserver com montagem de associação inicial
Para adicionar uma montagem vinculada de inicialização 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 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 C:\PostgreSQL\Init no Windows (ou /PostgreSQL/Init no Unix) no computador host do 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 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 pacote NuGet 📦 AspNetCore.HealthChecks.Npgsql.
integração Client
Para começar a usar a integração .NET AspirePostgreSQLclient, instale o 📦Aspire. O Npgsql pacote NuGet no projeto que consome client, ou seja, o projeto do aplicativo que usa o PostgreSQLclient. A integração PostgreSQLclient registra uma instância NpgsqlDataSource que você pode usar para interagir com PostgreSQL.
dotnet add package Aspire.Npgsql
Adicionar Npgsql client
No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddNpgsqlDataSource em qualquer IHostApplicationBuilder para registrar um NpgsqlDataSource a ser usado 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 PostgreSQLserver no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar PostgreSQLserverde recursos.
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 .NETde injeção de dependência.
Adicionar Npgsql com chave client
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 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 JSON de integração PostgreSQLclient completo, 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 desabilitar checagens de saúde.
builder.AddNpgsqlDataSource(
"postgresdb",
static settings => settings.DisableHealthChecks = true);
Exames 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.
- 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 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 AspirePostgreSQL usa as seguintes categorias de log:
Npgsql.ConnectionNpgsql.CommandNpgsql.TransactionNpgsql.CopyNpgsql.ReplicationNpgsql.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_secondec_Npgsql_bytes_read_per_secondec_Npgsql_commands_per_secondec_Npgsql_total_commandsec_Npgsql_current_commandsec_Npgsql_failed_commandsec_Npgsql_prepared_commands_ratioec_Npgsql_connection_poolsec_Npgsql_multiplexing_average_commands_per_batchec_Npgsql_multiplexing_average_write_time_per_batch
Azure PostgreSQL integração de hospedagem
Para implantar seus recursos de PostgreSQL em Azure, instale o pacote NuGet 📦Aspire.Hospedagem.Azure.PostgreSQL:
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 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 AzurePostgres Flexível Server.
Importante
O AddAzurePostgresFlexibleServer configura por padrão a autenticação do Microsoft Entra ID. Isso requer alterações em aplicativos que precisam se conectar a esses recursos. Para obter mais informações, consulte Client integração.
Adicionar Azure Npgsql autenticado client
Por padrão, quando você chama AddAzurePostgresFlexibleServer na sua integração de hospedagem PostgreSQL, ele configura o 📦Azure pacote NuGet de 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.AddNpgsqlDataSource(
"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.
