Aspire Azure PostgreSQL samverkan

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

Azure Database for PostgreSQL– Flexibel Server är en relationsdatabastjänst baserad på databasmotorn med öppen källkod Postgres. Det är en fullständigt hanterad databas som en tjänst som kan hantera verksamhetskritiska arbetsbelastningar med förutsägbar prestanda, säkerhet, hög tillgänglighet och dynamisk skalbarhet. Med integreringen AspireAzurePostgreSQL kan du ansluta till befintliga AzurePostgreSQL databaser eller skapa nya instanser från .NET med docker.io/library/postgres containeravbildningen.

Hostingtjänstintegration

Aspire Azure PostgreSQL värdtjänstintegration modellerar en PostgreSQL flexibel server och databas som typerna AzurePostgresFlexibleServerResource och AzurePostgresFlexibleServerDatabaseResource. Andra typer som är tillgängliga i värdintegrering representeras i följande resurser:

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Om du vill komma åt dessa typer och API:er för att uttrycka dem som resurser i ditt AppHost-projekt installerar du 📦Aspire. Hosting.Azure.PostgreSQL NuGet-paket:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

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

Azure PostgreSQL värdintegrering förlitar sig på 📦Aspire.Hosting.PostgreSQL NuGet-paketet och utökar det för att stödja Azure. Allt du kan göra med AspirePostgreSQL integrering och AspirePostgreSQLEntity Framework Core integrering kan du också göra med den här integreringen.

Lägga till AzurePostgreSQL serverresurs

När du har installerat AspireAzurePostgreSQL värdintegrering anropar AddAzurePostgresFlexibleServer du tilläggsmetoden i ditt AppHost-projekt:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Föregående anrop till AddAzurePostgresFlexibleServer konfigurerar PostgresSQL-serverresursen så att den distribueras som en AzurePostgres flexibel Server.

Ansluta till en befintlig AzurePostgreSQL flexibel server

Du kanske har en befintlig AzurePostgreSQL flexibel server som du vill ansluta till. Koppla ett anrop för att markera att din AzurePostgresFlexibleServerResource är en befintlig resurs.

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...

Mer information om hur du behandlar AzurePostgreSQL flexibla serverresurser som befintliga resurser finns i Använda befintliga Azure resurser.

Kör AzurePostgreSQL resurs som en container

Den AzurePostgreSQL värdintegrering stöder körning av PostgreSQL-servern som en lokal container. Detta är fördelaktigt för situationer där du vill köra PostgreSQL-servern lokalt i utvecklings- och testsyfte, så att du inte behöver etablera en Azure resurs eller ansluta till en befintlig AzurePostgreSQL server.

Om du vill köra PostgreSQL-servern som en container anropar du metoden 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);

Föregående kod konfigurerar en AzurePostgreSQL flexibel Server resurs för att köras lokalt i en container.

Konfigurera AzurePostgreSQL-servern att använda lösenordsautentisering

Som standard är AzurePostgreSQL-servern konfigurerad för att använda Microsoft Entra-ID autentisering. Om du vill använda lösenordsautentisering kan du konfigurera servern så att den använder lösenordsautentisering genom att anropa metoden 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);

Föregående kod konfigurerar AzurePostgreSQL-servern för att använda lösenordsautentisering. Parametrarna username och password läggs till i AppHost som parametrar och WithPasswordAuthentication metoden anropas för att konfigurera AzurePostgreSQL servern att använda lösenordsautentisering. Mer information finns i externa parametrar.

Konfigurationsgenererad Bicep

Om du är ny på Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med Aspirebehöver du inte skriva Bicep för hand eftersom etablerings-API:erna genererar Bicep åt dig. När du publicerar din app genereras Bicep-filen tillsammans med manifestfilen. När du lägger till en AzurePostgreSQL resurs genereras följande 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

Föregående Bicep är en modul som etablerar en AzurePostgreSQL flexibel serverresurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

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

Förutom den PostgreSQL flexibla servern etablerar den även en Azure brandväggsregel som tillåter alla Azure IP-adresser. Slutligen skapas en administratör för PostgreSQL-servern och anslutningssträngen matas ut som en utdatavariabel. Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa tillhandahållandeinfrastruktur

Alla AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör anpassning av det genererade Bicep genom att tillhandahålla ett flytande API för att konfigurera resurserna Azure med hjälp av API:et ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Du kan till exempel konfigurera kind, consistencyPolicy, locationsoch mycket mer. I följande exempel visas hur du anpassar PostgreSQL-serverresursen:

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

Föregående kod:

• Kedjar ett anrop till ConfigureInfrastructure-API:et:
  • Parametern infra är en instans av den AzureResourceInfrastructure typen.
  • De tillgängliga resurserna hämtas genom att anropa GetProvisionableResources()-metoden.
  • Den enstaka PostgreSqlFlexibleServer hämtas.
  • sku anges med PostgreSqlFlexibleServerSkuTier.Burstable.
  • Egenskaperna för hög tillgänglighet anges med PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant i standby-tillgänglighetszonen "2".
  • En tagg läggs till på den flexibla servern med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa PostgreSQL flexibel serverresurs. Mer information finns i Azure.Provisioning.PostgreSql och Azure. Anpassning av provisionering.

Client integration

Kom igång med klientintegrering AspireAzurePostgreSQL genom att installera 📦Aspire.Azure.Npgsql NuGet-paketet i det projekt som använder klienten, dvs. projektet för den applikation som använder PostgreSQL-klienten. PostgreSQL-klientintegrering registrerar en NpgsqlDataSource- instans som du kan använda för att interagera med PostgreSQL.

dotnet add package Aspire.Azure.Npgsql

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

Anslutningen PostgreSQL kan användas med klientintegration genom att anropa AddAzureNpgsqlDataSource:

builder.AddAzureNpgsqlDataSource(connectionName: "postgresdb");

Föregående kodfragment visar hur du använder AddAzureNpgsqlDataSource metoden för att registrera en NpgsqlDataSource instans som använder Azure autentisering (Microsoft Entra-ID). Det här "postgresdb" anslutningsnamnet motsvarar ett konfigurationsvärde för anslutningssträngen.

När du har lagt till NpgsqlDataSource i byggaren kan du hämta NpgsqlDataSource-instansen genom beroendeinjektion. Om du till exempel vill hämta datakällobjektet från en exempeltjänst definierar du det som en konstruktorparameter och kontrollerar att klassen ExampleService är registrerad med containern för beroendeinmatning:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nyckelad Azure Npgsql-klient

Det kan finnas situationer där du vill registrera flera NpgsqlDataSource instanser med olika anslutningsnamn. Om du vill registrera nyckelade Npgsql-klienter anropar du metoden AddKeyedAzureNpgsqlDataSource:

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

Sedan kan du hämta NpgsqlDataSource instanser genom beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om nyckelade tjänster finns i .NET beroendeinmatning: Nyckelade tjänster.

Konfiguration

Aspire Azure Npgsql-integreringen innehåller flera alternativ för att konfigurera databasanslutningen baserat på kraven och konventionerna i projektet.

Använda en anslutningssträng

När du använder en anslutningssträng som definierats i konfigurationsavsnittet ConnectionStrings anger du namnet på anslutningssträngen när du anropar AddAzureNpgsqlDataSource:

builder.AddAzureNpgsqlDataSource("postgresdb");

Anslutningssträngen hämtas från konfigurationsavsnittet ConnectionStrings , till exempel överväg följande JSON konfiguration:

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

Mer information om hur du konfigurerar anslutningssträngen finns i dokumentationen om Npgsql-anslutningssträngen.

Använda konfigurationsprovidrar

Npgsql-integreringen AspireAzure stöder Microsoft.Extensions.Configuration. Den läser in AzureNpgsqlSettings från konfigurationen Aspire:Azure:Npgsql med nyckeln. Tänk till exempel på följande appsettings.json fil som konfigurerar några av de tillgängliga alternativen:

{
  "Aspire": {
    "Npgsql": {
      "DisableHealthChecks": true,
      "DisableTracing": true
    }
  }
}

Använd inline-delegeringar

Du kan konfigurera inställningar i kod genom att skicka delegaten Action<AzureNpgsqlSettings> configureSettings för att konfigurera vissa eller alla alternativ direkt i koden, till exempel för att inaktivera hälsokontroller via kod.

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

Använd egenskapen AzureNpgsqlSettings.Credential för att upprätta en anslutning. Om inga autentiseringsuppgifter har konfigurerats används DefaultAzureCredential. När anslutningssträngen innehåller ett användarnamn och lösenord ignoreras autentiseringsuppgifterna.

Client hälsokontroller för integrering

Som standard Aspire har klientintegreringarhälsokontroller aktiverade för alla tjänster. På samma sätt möjliggör många Aspirehostingintegrationer även hälsokontrolländpunkter. Mer information finns i:

• .NET apphälsokontroller i C#
• Hälsokontroller i ASP.NET Core

• Lägger till NpgSqlHealthCheck, som verifierar att kommandon kan köras mot den underliggande Postgres databasen.
• Integrerar med /health HTTP-slutpunkt, vilket anger att alla registrerade hälsokontroller måste passera för att appen ska anses vara redo att acceptera trafik.

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Aspire PostgreSQL-integreringen använder följande loggkategorier:

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

Spårning

Aspire PostgreSQL-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• Npgsql

Mätvärden

Integreringen AspirePostgreSQL genererar följande mått med hjälp av 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

Se även

• PostgreSQL dokument
• Azure databas för PostgreSQL
• Aspire Azure PostgreSQL Entity Framework Core integration
• Aspire PostgreSQL integration
• Aspire Integrationer
• Aspire GitHub Repo