Sdílet prostřednictvím

integrace .NET AspireAzurePostgreSQL

  • Článek

zahrnuje:integrace hostování a Client integrace

Azure Database for PostgreSQL– flexibilní Server je relační databázová služba založená na opensourcovém databázovém stroji Postgres. Jedná se o plně spravovanou databázi jako službu, která dokáže zpracovávat důležité úlohy s předvídatelným výkonem, zabezpečením, vysokou dostupností a dynamickou škálovatelností. Integrace .NET AspireAzurePostgreSQL poskytuje způsob, jak se připojit k existujícím databázím AzurePostgreSQL nebo vytvořit nové instance z .NET pomocí image kontejnerudocker.io/library/postgres .

Integrace hostování

Integrace hostování .NET AspireAzurePostgreSQL modeluje PostgreSQL flexibilní server a databázi jako typy AzurePostgresFlexibleServerResource a AzurePostgresFlexibleServerDatabaseResource. Další typy, které jsou ze své podstaty dostupné v integraci hostování, jsou reprezentovány v následujících prostředcích:

Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření jako prostředků v projektu hostitele aplikace , nainstalujte balíček NuGet 📦Aspire.Hosting.Azure.PostgreSQL:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Další informace naleznete na dotnet add package.

Integrace hostování AzurePostgreSQL závisí na 📦Aspire.hostování.PostgreSQL balíčku NuGet, pro rozšíření podpory Azure. Všechno, co můžete dělat s integrací .NET AspirePostgreSQL a integrací .NET AspirePostgreSQLEntity Framework Core, s touto integrací můžete také provádět.

Přidání prostředku serveru AzurePostgreSQL

Po instalaci integrace hostování .NET AspireAzurePostgreSQL volejte metodu rozšíření AddAzurePostgresFlexibleServer v hostitelském projektu aplikace:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Předchozí volání AddAzurePostgresFlexibleServer nakonfiguruje prostředek serveru PostgreSQL tak, aby byl nasazen jako flexibilní AzurePostgresServer.

Důležitý

Ve výchozím nastavení AddAzurePostgresFlexibleServer konfiguruje ověřování ID Microsoft Entra. To vyžaduje změny aplikací, které se k těmto prostředkům potřebují připojit. Další informace najdete v tématu Client integrace.

Spropitné

Když voláte AddAzurePostgresFlexibleServer, implicitně vyvolá volání funkce AddAzureProvisioning– což přidává podporu pro dynamické vytváření prostředků Azure při startu aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Další informace naleznete v tématu Místní zřizování: Konfigurace.

Vygenerované nastavení Bicep

Pokud jste noví v Bicep, je to jazyk specifický pro doménu, určený k definování Azure prostředků. S .NET.NET Aspirenemusíte psát Bicep ručně, protože zřizovací API generuje Bicep za vás. Když publikujete aplikaci, vygenerovaný Bicep je výstupem společně se souborem manifestu. Když přidáte prostředek AzurePostgreSQL, vygeneruje se následující Bicep:


přepnout AzurePostgreSQL 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}'

Předchozí bicep je modul, který zřizuje flexibilní server AzurePostgreSQL s následujícími výchozími nastaveními:

  • authConfig: Konfigurace ověřování serveru PostgreSQL. Výchozí hodnota je ActiveDirectoryAuth povolená a PasswordAuth zakázaná.
  • availabilityZone: Zóna dostupnosti serveru PostgreSQL. Výchozí hodnota je 1.
  • backup: Konfigurace zálohování serveru PostgreSQL. Výchozí hodnota je BackupRetentionDays nastavená na 7 a GeoRedundantBackup nastavená na Disabled.
  • highAvailability: Konfigurace vysoké dostupnosti serveru PostgreSQL. Výchozí hodnota je Disabled.
  • storage: Konfigurace úložiště serveru PostgreSQL. Výchozí hodnota je StorageSizeGB nastavená na 32.
  • version: Verze serveru PostgreSQL. Výchozí hodnota je 16.
  • sku: Skladová položka serveru PostgreSQL. Výchozí hodnota je Standard_B1ms.
  • tags: Značky serveru PostgreSQL. Výchozí hodnota aspire-resource-name je nastavena na název prostředku Aspire, v tomto případě postgres-flexible.

Kromě flexibilního serveru PostgreSQL také zřídí pravidlo firewallu Azure, které povolí všechny IP adresy Azure. Nakonec se pro server PostgreSQL vytvoří správce a připojovací řetězec se vypíše jako výstupní proměnná. Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury zabezpečení

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicepu tím, že poskytuje plynulé rozhraní API pro konfiguraci Azure prostředků pomocí ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API. Můžete například nakonfigurovat kind, consistencyPolicy, locationsatd. Následující příklad ukazuje, jak přizpůsobit prostředek AzureAzure Cosmos DB:

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");
    });

Předchozí kód:

K dispozici je mnoho dalších možností konfigurace pro přizpůsobení prostředku flexibilního serveru PostgreSQL. Další informace najdete v tématu Azure.Provisioning.PostgreSql. Další informace najdete v tématu Azure. Přizpůsobení zajišťování.

Připojení k existujícímu flexibilnímu serveru AzurePostgreSQL

Možná máte existující AzurePostgreSQL flexibilní server, ke kterému se chcete připojit. Místo zavedení nového flexibilního serverového prostředku AzurePostgreSQL můžete k hostiteli aplikace přidat připojovací řetězec. Pokud chcete přidat připojení k existujícímu AzurePostgreSQL flexibilnímu serveru, zavolejte metodu 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...

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace vloží tento připojovací řetězec jako proměnnou prostředí do všech závislých prostředků, například:

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

Závislý prostředek má přístup k vložení připojovacího řetězce voláním metody GetConnectionString a zadáním názvu připojení jako parametr, v tomto případě "postgres". Rozhraní API GetConnectionString je zkratka pro IConfiguration.GetSection("ConnectionStrings")[name].

Spusťte prostředek AzurePostgreSQL jako kontejner

Integrace hostování AzurePostgreSQL podporuje spuštění serveru PostgreSQL jako místního kontejneru. To je užitečné v situacích, kdy chcete spustit PostgreSQL server místně pro účely vývoje a testování, abyste se vyhnuli nutnosti zřídit Azure prostředek nebo se připojit k existujícímu serveru AzurePostgreSQL.

Pokud chcete spustit PostgreSQL server jako kontejner, zavolejte metodu 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);

Předchozí kód nakonfiguruje prostředek AzurePostgreSQL Flexibilní Server tak, aby běžel místně v kontejneru.

Spropitné

Metoda RunAsContainer je užitečná pro místní vývoj a testování. Rozhraní API zveřejňuje volitelný delegát, který umožňuje přizpůsobit základní konfiguraci PostgresServerResource, jako je přidání nástroje pgAdmin, pgWeb, přidání datového svazku nebo připojení datové vazby a přidání připojení inicializační vazby. Další informace najdete v části .NET AspirePostgreSQL integrace hostování.

Nakonfigurujte server AzurePostgreSQL tak, aby používal ověřování heslem.

Ve výchozím nastavení je server AzurePostgreSQL nakonfigurovaný tak, aby používal ověřování ověřování Microsoft Entra ID. Pokud chcete použít ověřování heslem, můžete server nakonfigurovat tak, aby používal ověřování heslem zavoláním metody 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);

Předchozí kód nakonfiguruje server AzurePostgreSQL tak, aby používal ověřování heslem. Parametry username a password se přidají do hostitele aplikace jako parametry a volá se metoda WithPasswordAuthentication pro konfiguraci AzurePostgreSQL serveru tak, aby používal ověřování heslem. Další informace naleznete v tématu Externí parametry.

integrace Client

Pokud chcete začít s integrací klienta .NET AspirePostgreSQL, nainstalujte 📦Aspire. Npgsql balíček NuGet v projektu využívajícím klienta, tj. projekt aplikace, která používá klienta PostgreSQL. Integrace klienta PostgreSQL registruje instanci NpgsqlDataSource, kterou můžete použít k interakci s PostgreSQL.

dotnet add package Aspire.Npgsql

Přidání klienta Npgsql

V souboru Program.cs klientského projektu vyvolejte metodu rozšíření AddNpgsqlDataSource na libovolném IHostApplicationBuilder a zaregistrujte NpgsqlDataSource k použití pomocí kontejneru pro injektáž závislostí. Metoda přebírá parametr názvu připojení.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku serveru PostgreSQL v projektu hostitele aplikace. Další informace najdete v tématu Přidání prostředku serveru PostgreSQL.

Po přidání NpgsqlDataSource do tvůrce můžete získat instanci NpgsqlDataSource pomocí injektáže závislostí. Pokud například chcete načíst objekt zdroje dat z ukázkové služby, definujte ho jako parametr konstruktoru a ujistěte se, že je třída ExampleService zaregistrovaná v kontejneru injektáže závislostí:

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání klienta Npgsql s klíči

Mohou nastat situace, kdy budete chtít zaregistrovat více instancí NpgsqlDataSource s různými názvy připojení. Pokud chcete zaregistrovat klienty Npgsql s klíči, zavolejte metodu AddKeyedNpgsqlDataSource:

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

Potom můžete načíst instance NpgsqlDataSource pomocí injekce závislostí. Pokud například chcete načíst připojení z ukázkové služby:

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

Další informace o klíčových službách najdete v tématu .NET injektáž závislostí: klíčové služby.

Konfigurace

Integrace .NET AspirePostgreSQL poskytuje několik přístupů a možností konfigurace, které splňují požadavky a konvence projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání metody AddNpgsqlDataSource zadat název připojovacího řetězce:

builder.AddNpgsqlDataSource("postgresdb");

Připojovací řetězec se následně načte z oddílu konfigurace ConnectionStrings:

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

Další informace naleznete v ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspirePostgreSQL podporuje Microsoft.Extensions.Configuration. Načte NpgsqlSettings z appsettings.json nebo jiných konfiguračních souborů pomocí klíče Aspire:Npgsql. Příklad appsettings.json, který konfiguruje některé z možností:

Následující příklad ukazuje soubor appsettings.json, který konfiguruje některé z dostupných možností:

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

Kompletní schéma integrace klienta PostgreSQLJSON naleznete v části Aspire.Npgsql/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<NpgsqlSettings> configureSettings a nastavit některé nebo všechny možnosti přímo v kódu, například zakázat zdravotní kontroly:

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

Kontroly stavu

Integrace .NET.NET Aspire ve výchozím nastavení umožňují kontroly stavu pro všechny služby. Další informace naleznete v přehledu integrací .NET.NET Aspire.

  • Přidá NpgSqlHealthCheck, který ověří, že příkazy lze úspěšně spustit na podkladové Postgres databázi.
  • Integruje se s koncovým bodem HTTP /health, který stanoví, že všechny registrované kontroly stavu musí být úspěšné, aby byla aplikace považována za připravenou k přijímání provozu.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilířů pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspirePostgreSQL používá následující kategorie protokolů:

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

Trasování

Integrace .NET AspirePostgreSQL s použitím OpenTelemetryvygeneruje následující aktivity trasování:

  • Npgsql

Metriky

Integrace .NET AspirePostgreSQL pomocí OpenTelemetryvygeneruje následující metriky:

  • 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

Přidat ověřeného klienta Npgsql Azure

Ve výchozím nastavení se při volání AddAzurePostgresFlexibleServer v PostgreSQL hostování integrace nakonfiguruje 📦Azure. Identita balíčku NuGet pro povolení ověřování:

dotnet add package Azure.Identity

Připojení PostgreSQL je možné využívat pomocí integrace klienta a 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));
});

Předchozí fragment kódu ukazuje použití třídy DefaultAzureCredential z balíčku Azure.Identity k ověření pomocí Microsoft Entra ID a načtení tokenu pro připojení k databázi PostgreSQL. Metoda UsePeriodicPasswordProvider slouží k poskytnutí tokenu tvůrci připojovacího řetězce.

Viz také