Partilhar via

.NET Aspire Azure PostgreSQL integração

  • Artigo

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

Azure Database for PostgreSQL—Flexible Server é um serviço de banco de dados relacional baseado no mecanismo de banco de dados de código aberto Postgres. É um banco de dados como serviço totalmente gerenciado que pode lidar com cargas de trabalho de missão crítica com desempenho previsível, segurança, alta disponibilidade e escalabilidade dinâmica. A integração .NET AspireAzurePostgreSQL fornece uma maneira de se conectar a bancos de dados AzurePostgreSQL 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 .NET AspireAzurePostgreSQL modela um servidor e banco de dados PostgreSQL flexíveis conforme os tipos AzurePostgresFlexibleServerResource e AzurePostgresFlexibleServerDatabaseResource. Outros tipos que estão inerentemente disponíveis na integração de hospedagem são representados nos seguintes recursos:

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Para obter mais informações, consulte dotnet add package.

A integração de hospedagem AzurePostgreSQL depende do pacote NuGet 📦Aspire.Hosting.PostgreSQL, e este é estendido para oferecer suporte a Azure. Tudo o que tu podes fazer com a integração .NET AspirePostgreSQL e a integração .NET AspirePostgreSQLEntity Framework Core também podes fazer com esta integração.

Adicionar AzurePostgreSQL recurso do servidor

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 de servidor PostgreSQL para ser implementado como um AzurePostgres Flexível Server.

Importante

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

Dica

Quando você chama AddAzurePostgresFlexibleServer, ele chama implicitamente AddAzureProvisioning—que adiciona suporte para gerar recursos de Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, consulte Provisionamento local: Configuração.

Provisionamento gerado em Bicep

Se és novo no Bicep, é uma linguagem de domínio específico para a definição de recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, porque as APIs de provisionamento geram Bicep para você. Ao publicares a tua aplicação, o Bicep gerado é exibido juntamente com o ficheiro de manifesto. Ao adicionar um recurso AzurePostgreSQL, é gerado o seguinte Bicep:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalId string

param principalType string

param principalName string

resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = {
  name: take('postgresflexible-${uniqueString(resourceGroup().id)}', 63)
  location: location
  properties: {
    authConfig: {
      activeDirectoryAuth: 'Enabled'
      passwordAuth: 'Disabled'
    }
    availabilityZone: '1'
    backup: {
      backupRetentionDays: 7
      geoRedundantBackup: 'Disabled'
    }
    highAvailability: {
      mode: 'Disabled'
    }
    storage: {
      storageSizeGB: 32
    }
    version: '16'
  }
  sku: {
    name: 'Standard_B1ms'
    tier: 'Burstable'
  }
  tags: {
    'aspire-resource-name': 'postgres-flexible'
  }
}

resource postgreSqlFirewallRule_AllowAllAzureIps 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2024-08-01' = {
  name: 'AllowAllAzureIps'
  properties: {
    endIpAddress: '0.0.0.0'
    startIpAddress: '0.0.0.0'
  }
  parent: postgres_flexible
}

resource postgres_flexible_admin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01' = {
  name: principalId
  properties: {
    principalName: principalName
    principalType: principalType
  }
  parent: postgres_flexible
  dependsOn: [
    postgres_flexible
    postgreSqlFirewallRule_AllowAllAzureIps
  ]
}

output connectionString string = 'Host=${postgres_flexible.properties.fullyQualifiedDomainName};Username=${principalName}'

O Bicep anterior é um módulo que provisiona um servidor AzurePostgreSQL flexível com os seguintes padrões:

  • authConfig: A configuração de autenticação do servidor PostgreSQL. O padrão é ActiveDirectoryAuth ativado e PasswordAuth desabilitado.
  • availabilityZone: A zona de disponibilidade do servidor PostgreSQL. O padrão é 1.
  • backup: A configuração de backup do servidor PostgreSQL. O padrão é BackupRetentionDays definido como 7 e GeoRedundantBackup definido como Disabled.
  • highAvailability: A configuração de alta disponibilidade do servidor PostgreSQL. O padrão é Disabled.
  • storage: A configuração de armazenamento do servidor PostgreSQL. O padrão é StorageSizeGB definido como 32.
  • version: A versão do servidor PostgreSQL. O padrão é 16.
  • sku: O SKU do servidor PostgreSQL. O padrão é Standard_B1ms.
  • tags: Tags do servidor PostgreSQL. O padrão é aspire-resource-name definido como o nome do recurso Aspire, neste caso postgres-flexible.

Além do servidor PostgreSQL flexível, ele também provisiona uma regra de Firewall Azure para permitir todos os Azure endereços IP. Finalmente, um administrador é criado para o servidor PostgreSQL e a cadeia de conexão é gerada como uma variável de saída. O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite a personalização do Bicep gerado fornecendo uma API fluente para configurar os recursos Azure usando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o kind, consistencyPolicy, locationse muito mais. O exemplo a seguir demonstra como personalizar o recurso de servidor PostgreSQL:

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var flexibleServer = infra.GetProvisionableResources()
                                  .OfType<PostgreSqlFlexibleServer>()
                                  .Single();

        flexibleServer.Sku = new PostgreSqlFlexibleServerSku
        {
            Tier = PostgreSqlFlexibleServerSkuTier.Burstable,
        };
        flexibleServer.HighAvailability = new PostgreSqlFlexibleServerHighAvailability
        {
            Mode = PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant,
            StandbyAvailabilityZone = "2",
        };
        flexibleServer.Tags.Add("ExampleKey", "Example value");
    });

O código anterior:

Há muito mais opções de configuração disponíveis para personalizar o recurso de servidor PostgreSQL flexível. Para obter mais informações, consulte Azure.Provisioning.PostgreSql e Azure. Personalização do provisionamento.

Conectar-se a um servidor flexível AzurePostgreSQL existente

Você pode ter um servidor existente AzurePostgreSQL flexível ao qual deseja se conectar. Em vez de representar um novo recurso de servidor AzurePostgreSQL flexível, você pode adicionar uma cadeia de conexão ao host do aplicativo. Para adicionar uma conexão a um servidor existente AzurePostgreSQL flexível, chame o método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(postgres);

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

Observação

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Na nomenclatura .NET.NET Aspire, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host da aplicação, normalmente sob a seção Segredos do Utilizador, na secção ConnectionStrings. O host do aplicativo injeta essa cadeia de conexão como uma variável de ambiente em todos os recursos dependentes, por exemplo:

{
    "ConnectionStrings": {
        "postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
    }
}

O recurso dependente pode acessar a cadeia de conexão injetada chamando o método GetConnectionString e passando o nome da conexão como parâmetro, neste caso "postgres". A API GetConnectionString é uma abreviação de IConfiguration.GetSection("ConnectionStrings")[name].

Executar AzurePostgreSQL recurso como um contêiner

A integração de hospedagem AzurePostgreSQL suporta a execução do servidor PostgreSQL como um contêiner local. Isso é benéfico para situações em que você deseja executar o servidor PostgreSQL localmente para fins de desenvolvimento e teste, evitando a necessidade de provisionar um recurso Azure ou conectar-se a um servidor AzurePostgreSQL existente.

Para executar o servidor PostgreSQL como um contêiner, chame o método RunAsContainer:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .RunAsContainer();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

O código anterior configura um recurso AzurePostgreSQL Flexible Server para ser executado localmente em um contêiner.

Dica

O método RunAsContainer é útil para o desenvolvimento local e testes. A API expõe um delegado opcional que permite personalizar a configuração de PostgresServerResource subjacente. Por exemplo, pode-se adicionar o pgAdmin e o pgWeb, adicionar um volume de dados ou montagem de diretório de dados, e adicionar uma montagem de diretório de inicialização. Para obter mais informações, consulte a seção .NET AspirePostgreSQL de integração de hospedagem.

Configurar o servidor AzurePostgreSQL para usar a autenticação de senha

Por padrão, o servidor AzurePostgreSQL está configurado para usar a autenticação do Microsoft Entra ID . Se você quiser usar a autenticação de senha, você pode configurar o servidor para usar a autenticação de senha chamando o método WithPasswordAuthentication:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .WithPasswordAuthentication(username, password);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

O código anterior configura o servidor AzurePostgreSQL para usar a autenticação de senha. Os parâmetros username e password são adicionados ao host do aplicativo como parâmetros, e o método WithPasswordAuthentication é chamado para configurar o servidor AzurePostgreSQL para usar a autenticação de senha. Para obter mais informações, consulte Parâmetros externos.

Client integração

Para começar com a integração do cliente .NET AspirePostgreSQL, instale o pacote NuGet 📦Aspire.Npgsql no projeto que consome o cliente, isto é, o projeto para a aplicação que usa o cliente PostgreSQL. A integração do cliente PostgreSQL regista uma instância de NpgsqlDataSource que pode ser usada para interagir com PostgreSQL.

dotnet add package Aspire.Npgsql

Adicionar cliente Npgsql

No arquivo 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 container 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 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ê 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, pode-se 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 identificados por chave, consulte a seção .NET sobre injeção de dependência: Serviços identificados por 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 um string 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. Ele carrega o NpgsqlSettings de appsettings.json ou outros ficheiros de configuração utilizando 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 o esquema completo de integração do cliente PostgreSQLJSON, consulte Aspire. Npgsql/ConfigurationSchema.json.

Usar delegados em linha

Você também pode passar o delegado Action<NpgsqlSettings> configureSettings para configurar algumas ou todas as opções em linha, por exemplo, para desativar as verificações de integridade.

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

Client verificações de saúde de integração

Por padrão, as .NET.NET Aspireintegrações de cliente têm as verificações de integridade habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também ativam endpoints para verificação de integridade. Para 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 com o endpoint HTTP /health, que especifica que todas as verificações de saúde registadas devem passar 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 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 usando 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

Adicionar cliente Npgsql autenticado Azure

Por padrão, ao chamar AddAzurePostgresFlexibleServer na integração de hospedagem PostgreSQL, o pacote NuGet 📦Azure.Identity é configurado para permitir a autenticação:

dotnet add package Azure.Identity

A conexão PostgreSQL pode ser consumida usando a integração com o cliente 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 trecho de código anterior demonstra como usar a classe DefaultAzureCredential do pacote Azure.Identity para autenticar com o ID do Microsoft Entra e recuperar um token para se conectar à base de dados PostgreSQL. O método UsePeriodicPasswordProvider é utilizado para fornecer o token ao construtor da cadeia de conexão.

Ver também