Compartilhar via

integração .NET AspireAzurePostgreSQL

Inclui:Integração de hospedagem incluída —&— Client Integração incluídaClient

Azure Banco de dados para PostgreSQL—Flexível Server é um serviço de banco de dados relacional baseado no mecanismo de banco de dados de software livre Postgres. É um banco de dados como serviço totalmente gerenciado que pode lidar com cargas de trabalho críticas 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

Os .NET AspireAzurePostgreSQL modelos de integração de hospedagem representam um servidor e banco de dados flexíveis como os tipos PostgreSQL e AzurePostgresFlexibleServerResource. Outros tipos que estão inerentemente disponíveis na integração de hospedagem são representados nos seguintes recursos:

Para acessar esses tipos e APIs para expressá-los como recursos em seu projeto de hospedagem de aplicativo , 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 tem uma dependência no pacote NuGet 📦Aspire.HostingPostgreSQL, estendendo-o para dar suporte a Azure. Tudo o que você pode fazer com a integração .NET AspirePostgreSQL e a integração .NET AspirePostgreSQLEntity Framework Core você também pode fazer com essa integração.

Adicionar AzurePostgreSQL recurso de servidor

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

Importante

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

Dica

Quando você chama AddAzurePostgresFlexibleServer, ele chama implicitamente AddAzureProvisioning— o que adiciona suporte para gerar recursos 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.

Bicep gerado pelo provisionamento

Se você ainda não conhece o Bicep, trata-se de uma linguagem de domínio específico para definir recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, pois as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é exibido junto com o arquivo de manifesto. Quando você adiciona um recurso AzurePostgreSQL, é gerado o seguinte código Bicep:

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

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
}

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

output name string = postgres_flexible.name

O Bicep anterior é um módulo que provisiona um AzurePostgreSQL recurso de servidor flexível. Além disso, as atribuições de função são criadas para o Azure recurso em um módulo separado:

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

param postgres_flexible_outputs_name string

param principalType string

param principalId string

param principalName string

resource postgres_flexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' existing = {
  name: postgres_flexible_outputs_name
}

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

Além do servidor flexível PostgreSQL, ele também provisiona uma regra de Firewall Azure para permitir o acesso a todos os endereços IP Azure. Por fim, um administrador é criado para o servidor PostgreSQL e a cadeia de conexão é gerada como uma variável de saída. O Bicep gerado é um ponto de partida e é influenciado por alterações na infraestrutura de provisionamento em C#. As personalizações feitas diretamente no arquivo Bicep serão substituídas, portanto, faça alterações por meio das APIs de provisionamento do C# para garantir que elas sejam refletidas nos arquivos gerados.

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 ao disponibilizar uma API fluente para configurar os recursos de 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.AddAzurePostgresFlexibleServer("postgres")
    .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á muitas outras opções de configuração disponíveis para personalizar o PostgreSQL recurso de servidor flexível. Para obter mais informações, consulte Azure.Provisioning.PostgreSql e Azure. Personalização de provisionamento.

Conectar-se a um servidor flexível AzurePostgreSQL existente

Você pode ter um servidor AzurePostgreSQL flexível existente ao qual deseja se conectar. Encadear uma chamada para anotar que o recurso AzurePostgresFlexibleServerResource é existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingPostgresName = builder.AddParameter("existingPostgresName");
var existingPostgresResourceGroup = builder.AddParameter("existingPostgresResourceGroup");

var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
                      .AsExisting(existingPostgresName, existingPostgresResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(postgres);

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

Para obter mais informações sobre como tratar AzurePostgreSQL recursos de servidor flexíveis como recursos existentes, consulte Usar recursos existentesAzure.

Nota

Como alternativa, em vez de representar um AzurePostgreSQL recurso de servidor flexível, você pode adicionar uma cadeia de conexão ao host do aplicativo. Essa abordagem é de tipo fraco e não funciona com atribuições de função ou personalizações de infraestrutura. Para obter mais informações, consulte Adicionar recursos existentes com cadeias de conexãoAzure.

Executar AzurePostgreSQL recurso como um contêiner

A AzurePostgreSQL integração de hospedagem dá suporte à 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 de Azure Flexível PostgreSQLServer para ser executado localmente em um contêiner.

Dica

O método RunAsContainer é útil para desenvolvimento e teste locais. A API expõe um delegado opcional que permite personalizar a configuração de PostgresServerResource subjacente. Por exemplo, você pode adicionar o pgAdmin e o pgWeb, adicionar um volume de dados ou fazer uma vinculação de dados, e também realizar uma vinculação de inicialização. Para obter mais informações, consulte a seção de integração de hospedagem .NET AspirePostgreSQL.

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

Por padrão, o servidor AzurePostgreSQL está configurado para usar a autenticação da ID do Microsoft Entra . Se você quiser usar a autenticação de senha, poderá 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.

integração Client

Para começar com a integração do cliente .NET AspireAzurePostgreSQL, instale o pacote NuGet 📦Aspire.Azure.Npgsql no projeto que consome o cliente, ou seja, o projeto para o aplicativo que usa o cliente PostgreSQL. A integração do cliente PostgreSQL registra uma instância de NpgsqlDataSource que você pode usar para interagir com PostgreSQL.

dotnet add package Aspire.Azure.Npgsql

A conexão PostgreSQL pode ser consumida pela integração do cliente ao chamar o AddAzureNpgsqlDataSource:

builder.AddAzureNpgsqlDataSource(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.

O snippet de código anterior demonstra como usar o método AddAzureNpgsqlDataSource para registrar uma instância NpgsqlDataSource que usa a autenticação Azure (ID do Microsoft Entra). Esse "postgresdb" nome de conexão corresponde a um valor de configuração de cadeia de conexão.

Depois de adicionar NpgsqlDataSource ao construtor, você pode obter a instância NpgsqlDataSource por meio de 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 Azure

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 AddKeyedAzureNpgsqlDataSource:

builder.AddKeyedAzureNpgsqlDataSource(name: "sales_db");
builder.AddKeyedAzureNpgsqlDataSource(name: "inventory_db");

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

public class ExampleService(
    [FromKeyedServices("sales_db")] NpgsqlDataSource salesDataSource,
    [FromKeyedServices("inventory_db")] NpgsqlDataSource inventoryDataSource)
{
    // Use data sources...
}

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

Configuração

A .NET AspireAzure integração do Npgsql fornece várias opções para configurar a conexão de banco de dados com base nos requisitos e convenções do seu projeto.

Usar uma string de conexão

Ao usar uma cadeia de conexão definida na ConnectionStrings seção de configuração, você fornece o nome da cadeia de conexão ao chamar AddAzureNpgsqlDataSource:

builder.AddAzureNpgsqlDataSource("postgresdb");

A cadeia de conexão é recuperada da ConnectionStrings seção de configuração, por exemplo, considere a seguinte JSON configuração:

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

Para obter mais informações sobre como configurar a cadeia de conexão, consulte a documentação da cadeia de conexão Npgsql.

Nota

O nome de usuário e a senha são automaticamente inferidos da credencial fornecida nas configurações.

Usar provedores de configuração

A integração .NET Aspire Npgsql suporta AzureMicrosoft.Extensions.Configuration. Ele carrega a AzureNpgsqlSettings da configuração usando a chave Aspire:Azure:Npgsql. Por exemplo, considere o seguinte arquivo appsettings.json que configura algumas das opções disponíveis:

{
  "Aspire": {
    "Npgsql": {
      "DisableHealthChecks": true,
      "DisableTracing": true
    }
  }
}
Usar delegados em linha

Você pode configurar as definições no código passando a função de delegação Action<AzureNpgsqlSettings> configureSettings para configurar algumas ou todas as opções diretamente. Por exemplo, para desabilitar verificações de integridade via código:

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

Use a propriedade AzureNpgsqlSettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, o DefaultAzureCredential será usado. Quando a cadeia de conexão contém um nome de usuário e senha, a credencial é ignorada.

Client checagens de saúde de integração

Por padrão, .NET.NET Aspireintegrações com clientes 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 todos os pontos de verificação de saúde registrados devem ser concluídos com êxito para que o aplicativo seja considerado pronto para aceitar tráfego.

Observabilidade e telemetria

As integrações de .NET.NET Aspire configuram automaticamente Registro, Rastreamento e Métricas, que são às vezes conhecidos 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.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

Consulte também