.NET Aspire Azure PostgreSQL integráció

Tartalmazza: Üzemeltetési integráció és Client integráció

Azure Database for PostgreSQL– A rugalmas Server egy nyílt forráskódú Postgres adatbázismotoron alapuló relációsadatbázis-szolgáltatás. Ez egy teljes mértékben felügyelt adatbázis szolgáltatásként, amely kiszámítható teljesítménnyel, biztonsággal, magas rendelkezésre állással és dinamikus skálázhatósággal képes kezelni a kritikus fontosságú számítási feladatokat. A .NET AspireAzurePostgreSQL integráció lehetővé teszi a meglévő AzurePostgreSQL adatbázisokhoz való csatlakozást, vagy új példányok létrehozását .NET a docker.io/library/postgres konténerképhasználatával.

Üzemeltetési integráció

Az .NET AspireAzurePostgreSQL integráció egy PostgreSQL rugalmas kiszolgálót és adatbázist modellez a AzurePostgresFlexibleServerResource és AzurePostgresFlexibleServerDatabaseResource típusokként. Az üzemeltetési integrációban eredendően elérhető egyéb típusok a következő erőforrásokban jelennek meg:

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Ha erőforrásként szeretné elérni ezeket a típusokat és API-kat az alkalmazáshoszt projektben, telepítse a 📦Aspire.Hosting.Azure.PostgreSQL NuGet csomagot:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

<PackageReference Include="Aspire.Hosting.Azure.PostgreSQL"
                  Version="*" />

A AzurePostgreSQL hosztingintegráció a 📦Aspire.Hosting.PostgreSQL NuGet-csomagra támaszkodik, ami kiterjeszti a Azure támogatását. Amit az integrációval és a integrációval megtehet, azt ezzel az integrációval is megteheti.

Azure PostgreSQL kiszolgálói erőforrás hozzáadása

Miután telepítette a .NET AspireAzurePostgreSQL üzemeltetési integrációt, hívja meg a AddAzurePostgresFlexibleServer bővítménymetódust az alkalmazásgazdaprojektben:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Az előző AddAzurePostgresFlexibleServer hívás konfigurálja a PostgresSQL szerver erőforrását, hogy AzurePostgres rugalmas Server konfigurációban kerüljön üzembe helyezésre.

Generált erőforrás-ellátás Bicep

Ha most ismerkedik a Bicepnyelvvel, ez egy tartományspecifikus nyelv az Azure erőforrások definiálására. A .NET.NET Aspiresegítségével Önnek nem kell kézzel írnia a Bicep-et, mert a kiépítési API létrehozza a Bicep-et az Ön számára. Az alkalmazás közzétételekor a generált Bicep a kimeneti fájlok között jelenik meg a jegyzékfájl mellett. Azure PostgreSQL erőforrás hozzáadásakor a következő Bicep jön létre:

@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}'

Az előző Bicep egy olyan modul, amely egy AzurePostgreSQL rugalmas kiszolgálót helyez üzembe a következő alapértelmezett értékekkel:

• authConfig: A PostgreSQL kiszolgáló hitelesítési konfigurációja. Az alapértelmezett érték ActiveDirectoryAuth engedélyezve van, és PasswordAuth le van tiltva.
• availabilityZone: A PostgreSQL kiszolgáló rendelkezésre állási zónája. Az alapértelmezett érték a 1.
• backup: A PostgreSQL-kiszolgáló biztonsági mentési konfigurációja. Az alapértelmezett érték BackupRetentionDays7 és GeoRedundantBackupDisabledértékre van állítva.
• highAvailability: A PostgreSQL kiszolgáló magas rendelkezésre állású konfigurációja. Az alapértelmezett érték a Disabled.
• storage: A PostgreSQL kiszolgáló tárolási konfigurációja. Az alapértelmezett érték StorageSizeGB van állítva 32-re.
• version: A PostgreSQL kiszolgáló verziója. Az alapértelmezett érték a 16.
• sku: A PostgreSQL szerver SKU-ja. Az alapértelmezett érték a Standard_B1ms.
• tags: A PostgreSQL kiszolgáló címkéi. Az alapértelmezett érték aspire-resource-name az Aspire erőforrás nevére van állítva, ebben az esetben postgres-flexible.

A rugalmas PostgreSQL kiszolgáló mellett egy Azure tűzfalszabályt is kiépít, amely lehetővé teszi az összes Azure IP-címet. Végül létrejön egy rendszergazda a PostgreSQL-kiszolgálóhoz, és a kapcsolati lánc kimeneti változóként jelenik meg. A létrehozott Bicep kiindulási pont, és testre szabható az adott követelményeknek megfelelően.

Az ellátási infrastruktúra testreszabása

Minden .NET AspireAzure erőforrás a AzureProvisioningResource típusú alosztály. Ez a típus lehetővé teszi a létrehozott Bicep testreszabását azáltal, hogy egy folyékony API-val konfigurálja a Azure erőforrásokat a ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API használatával. Konfigurálhatja például a kind, consistencyPolicy, locationsstb. Az alábbi példa bemutatja, hogyan szabhatja testre a PostgreSQL kiszolgálóerőforrást:

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

Az előző kód:

• A hívást az ConfigureInfrastructure API-hoz láncolja:
  • A infra paraméter a AzureResourceInfrastructure típusú példány.
  • A kiosztható erőforrások a GetProvisionableResources() metódus meghívásával kérhetők le.
  • Az egyetlen PostgreSqlFlexibleServer példány vissza lett kérve.
  • A sku a(z) PostgreSqlFlexibleServerSkuTier.Burstable-gyel van beállítva.
  • A magas rendelkezésre állási tulajdonságok PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant vannak beállítva a készenléti rendelkezésre állási zónában "2".
  • A rendszer hozzáad egy címkét a rugalmas kiszolgálóhoz ExampleKey kulccsal és Example valueértékkel.

A PostgreSQL rugalmas kiszolgálóerőforrás testreszabásához számos további konfigurációs lehetőség áll rendelkezésre. További információ: Azure.Provisioning.PostgreSql, valamint Azure. Testreszabás konfigurálása.

Csatlakozás meglévő AzurePostgreSQL rugalmas kiszolgálóhoz

Lehet, hogy rendelkezik egy meglévő AzurePostgreSQL rugalmas kiszolgálóval, amelyhez csatlakozni szeretne. Az új AzurePostgreSQL rugalmas kiszolgálóerőforrás helyett csatlakozási karakterláncot adhat hozzá az alkalmazás szolgáltatójához. Ha meglévő AzurePostgreSQL rugalmas kiszolgálóhoz szeretne kapcsolatot létesíteni, hívja meg a AddConnectionString metódust:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

A csatlakozási karakterlánc az alkalmazásházigazda beállításaiban van beállítva, általában a Felhasználói titkos kódokalatt, a ConnectionStrings szakaszban. Az alkalmazásgazda környezeti változóként injektálja ezt a kapcsolati sztringet az összes függő erőforrásba, például:

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

A függő erőforrás a GetConnectionString metódus meghívásával és a kapcsolatnév paraméterként való átadásával érheti el az injektált kapcsolati sztringet, ebben az esetben "postgres". A GetConnectionString API a IConfiguration.GetSection("ConnectionStrings")[name]rövidítése.

Futtassa a AzurePostgreSQL erőforrást konténerként.

A AzurePostgreSQL üzemeltetési integráció támogatja a PostgreSQL-kiszolgáló helyi tárolóként való futtatását. Ez olyan helyzetekben hasznos, amikor a PostgreSQL-kiszolgálót helyileg szeretné futtatni fejlesztési és tesztelési célokra, elkerülve, hogy ki kell építenie egy Azure erőforrást, vagy csatlakoznia kell egy meglévő AzurePostgreSQL-kiszolgálóhoz.

A PostgreSQL kiszolgáló tárolóként való futtatásához hívja meg a RunAsContainer metódust:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Az előző kód egy AzurePostgreSQL rugalmas Server erőforrást konfigurál, hogy helyileg fusson egy tárolóban.

A AzurePostgreSQL-kiszolgáló konfigurálása jelszóhitelesítés használatára

Alapértelmezés szerint a AzurePostgreSQL kiszolgáló úgy van konfigurálva, hogy Microsoft Entra-azonosítót hitelesítést használjon. Ha jelszóhitelesítést szeretne használni, konfigurálhatja a kiszolgálót jelszó-hitelesítés használatára a WithPasswordAuthentication metódus meghívásával:

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

Az előző kód a AzurePostgreSQL kiszolgálót jelszó-hitelesítés használatára konfigurálja. A username és password paraméterek paraméterként vannak hozzáadva az alkalmazás gazdagépéhez, a WithPasswordAuthentication metódus pedig a jelszó-hitelesítés használatára konfigurálja a AzurePostgreSQL-kiszolgálót. További információ: Külső paraméterek.

Client integráció

Az .NET AspirePostgreSQL kliensintegráció első lépéséhez telepítse a 📦Aspire.Npgsql NuGet-csomagot az ügyfélfogyasztó projektben, vagyis a PostgreSQL klienst használó alkalmazás projektjében. A PostgreSQL ügyfélintegráció regisztrál egy NpgsqlDataSource-példányt, amelyet arra használhat, hogy kapcsolatba lépjen a PostgreSQL-tal.

dotnet add package Aspire.Npgsql

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

Npgsql-ügyfél hozzáadása

Az ügyfélprojekt Program.cs fájljában hívja meg a AddNpgsqlDataSource kiterjesztési metódust bármely IHostApplicationBuilder esetén, hogy egy NpgsqlDataSource-t regisztráljon a függőséginjektáló konténeren keresztüli használatra. A metódus egy kapcsolatnévparamétert használ.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Miután hozzáadta a NpgsqlDataSource elemet a szerkesztőhöz, függőséginjektálással lekérheti a NpgsqlDataSource példányt. Ha például egy példaszolgáltatásból szeretné lekérni az adatforrás-objektumot, konstruktorparaméterként határozza meg, és győződjön meg arról, hogy a ExampleService osztály regisztrálva van a függőséginjektálási tárolóban:

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

További információ a függőséginjektálásról: .NET függőséginjektálás.

Kulcsos Npgsql-ügyfél hozzáadása

Előfordulhatnak olyan helyzetek, amikor több NpgsqlDataSource példányt szeretne regisztrálni különböző kapcsolatnevekkel. A kulcsos Npgsql-ügyfelek regisztrálásához hívja meg a AddKeyedNpgsqlDataSource metódust:

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

Ezután függőséginjektálással lekérheti a NpgsqlDataSource példányokat. Ha például egy példaszolgáltatásból szeretné lekérni a kapcsolatot:

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

További információ a kulcsos szolgáltatásokról: .NET függőséginjektálás: Kulcsos szolgáltatások.

Konfiguráció

A .NET AspirePostgreSQL integráció több konfigurációs módszert és lehetőséget kínál a projekt követelményeinek és konvencióinak teljesítéséhez.

Kapcsolati karakterlánc használata

Ha a ConnectionStrings konfigurációs szakaszból használ kapcsolati sztringet, megadhatja a kapcsolati sztring nevét a AddNpgsqlDataSource metódus meghívásakor:

builder.AddNpgsqlDataSource("postgresdb");

Ezután a ConnectionStrings konfigurációs szakaszból lesz lekérve a kapcsolati lánc.

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

További információért lásd a ConnectionString.

Konfigurációs szolgáltatók használata

A .NET AspirePostgreSQL integráció támogatja a Microsoft.Extensions.Configuration. Betölti a NpgsqlSettings-t a appsettings.json-ről vagy más konfigurációs fájlokból a Aspire:Npgsql kulcs segítségével. Példa appsettings.json, amely konfigurál néhány beállítást:

Az alábbi példa egy appsettings.json fájlt mutat be, amely konfigurálja a rendelkezésre álló lehetőségek némelyikét:

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

A teljes PostgreSQL ügyfél-integrációs JSON sémát lásd: Aspire. Npgsql/ConfigurationSchema.json.

Használjon beágyazott delegáltakat

A Action<NpgsqlSettings> configureSettings delegáltat átadhatja a beállítások egy részének vagy mindegyikének közvetlen beállítására, például egészségügyi ellenőrzések letiltására.

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

Client integrációs egészségügyi ellenőrzések

Alapértelmezés szerint .NET.NET Aspireügyfélintegrációkállapotellenőrzései engedélyezve vannak az összes szolgáltatáshoz. Hasonlóképpen számos .NET.NET Aspireüzemeltetési integráció is lehetővé teszi az állapot-ellenőrzési végpontokat. További információ:

• .NET alkalmazás-egészségügyi ellenőrzések C#-ben
• egészségügyi állapot-ellenőrzések ASP.NET Core

• Hozzáadja a NpgSqlHealthCheck, amely ellenőrzi, hogy a parancsok sikeresen végrehajthatók-e a mögöttes Postgres adatbázison.
• Integrálható a /health HTTP-végponttal, amely meghatározza, hogy az összes regisztrált állapot-ellenőrzésnek át kell mennie ahhoz, hogy az alkalmazás készen álljon a forgalom elfogadására

Megfigyelhetőség és telemetria

.NET .NET Aspire integrációk automatikusan beállítják a naplózási, nyomkövetési és metrikakonfigurációkat, amelyeket néha úgy is neveznek, mint a megfigyelhetőség alappillérei. Az integráció megfigyelhetőségéről és telemetriáról további információt .NET.NET Aspire integrációk áttekintésében. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban ismertetett technikákkal is letilthatók.

Fakitermelés

Az .NET AspirePostgreSQL integráció a következő naplókategóriákat használja:

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

Nyomkövetés

Az .NET AspirePostgreSQL integráció a következő nyomkövetési tevékenységeket bocsátja ki a OpenTelemetryhasználatával:

• Npgsql

Metrikák

Az .NET AspirePostgreSQL integráció a következő metrikákat bocsátja ki a OpenTelemetryhasználatával:

• 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

Hitelesített Npgsql-ügyfél hozzáadása Azure

Alapértelmezés szerint, amikor a -t meghívja a üzemeltetési integrációban, az konfigurálja az Identity NuGet-csomagot a hitelesítés engedélyezésére.

dotnet add package Azure.Identity

<PackageReference Include="Azure.Identity"
                  Version="*" />

A PostgreSQL kapcsolat az ügyfélintegráción keresztül és a Azure.Identity használatával érhető el.

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

Az előző kódrészlet bemutatja, hogyan használhatja a DefaultAzureCredential csomag Azure.Identity osztályát Microsoft Entra-azonosítóval való hitelesítéshez, és hogyan kér le egy jogkivonatot a PostgreSQL adatbázishoz való csatlakozáshoz. A UsePeriodicPasswordProvider metódus biztosítja a jogkivonatot a kapcsolati karakterlánc-építőnek.

Lásd még:

• PostgreSQL dokumentumok
• Azure adatbázis PostgreSQL számára
• .NET Aspire Azure PostgreSQL Entity Framework Core integráció
• .NET Aspire PostgreSQL integráció
• .NET .NET Aspire integrációk
• .NET Aspire GitHub repo