Dela via

.NET Aspire Azure PostgreSQL integration

  • Artikel

omfattar: Hosting-integration och Client integrering

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 .NET AspireAzurePostgreSQL kan du ansluta till befintliga AzurePostgreSQL databaser eller skapa nya instanser från .NET med docker.io/library/postgres containeravbildningen.

Värdintegrering

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

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

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Mer information finns i dotnet add package.

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 .NET AspirePostgreSQL integrering och .NET AspirePostgreSQLEntity Framework Core integrering kan du också göra med den här integreringen.

Lägga till AzurePostgreSQL serverresurs

När du har installerat .NET AspireAzurePostgreSQL värdintegrering anropar du AddAzurePostgresFlexibleServer-tilläggsmetoden i appvärdprojektet:

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.

Viktig

Som standard konfigurerar AddAzurePostgresFlexibleServerMicrosoft Entra-ID autentisering. Detta kräver ändringar i program som behöver ansluta till dessa resurser. Mer information finns i Client integration.

Tips

När du anropar AddAzurePostgresFlexibleServeranropas implicit AddAzureProvisioning– vilket ger stöd för att generera Azure resurser dynamiskt under appstarten. Appen måste konfigurera lämplig prenumeration och plats. Mer information finns i Lokal provisionering: Konfiguration.

Genererat tillhandahållande av Bicep

Om du är ny på Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med .NET.NET 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

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

Föregående Bicep är en modul som etablerar en AzurePostgreSQL flexibel server med följande standardvärden:

  • authConfig: Autentiseringskonfigurationen för PostgreSQL-servern. Standardvärdet är ActiveDirectoryAuth aktiverat och PasswordAuth inaktiverat.
  • availabilityZone: Tillgänglighetszonen för PostgreSQL-servern. Standardvärdet är 1.
  • backup: Säkerhetskopieringskonfigurationen för PostgreSQL-servern. Standardvärdet är BackupRetentionDays inställt på 7 och GeoRedundantBackup anges till Disabled.
  • highAvailability: Konfiguration av hög tillgänglighet för PostgreSQL-servern. Standardvärdet är Disabled.
  • storage: Lagringskonfigurationen för PostgreSQL-servern. Standardvärdet är StorageSizeGB inställt på 32.
  • version: Versionen av PostgreSQL-servern. Standardvärdet är 16.
  • sku: SKU:n för PostgreSQL-servern. Standardvärdet är Standard_B1ms.
  • tags: Taggarna för PostgreSQL-servern. Standardvärdet är aspire-resource-name inställt på namnet på den Aspire resursen, i det här fallet 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-mallen är en utgångspunkt och kan anpassas för att möta dina specifika behov.

Anpassa tillhandahållandeinfrastruktur

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

Föregående kod:

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.

Ansluta till en befintlig AzurePostgreSQL flexibel server

Du kanske har en befintlig AzurePostgreSQL flexibel server som du vill ansluta till. I stället för att representera en ny AzurePostgreSQL flexibel serverresurs kan du lägga till en anslutningssträng till programvärden. Om du vill lägga till en anslutning till en befintlig AzurePostgreSQL flexibel server anropar du metoden 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...

Anmärkning

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Anslutningssträngen konfigureras i appvärdens konfiguration, vanligtvis under Användarhemligheter, under avsnittet ConnectionStrings. Appvärden injekterar den här anslutningssträngen som en miljövariabel i alla resurser som är beroende, till exempel:

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

Den beroende resursen kan komma åt den inmatade anslutningssträngen genom att anropa metoden GetConnectionString och skicka anslutningsnamnet som parameter, i det här fallet "postgres". API:et GetConnectionString är en förkortning för IConfiguration.GetSection("ConnectionStrings")[name].

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.

Tips

Metoden RunAsContainer är användbar för lokal utveckling och testning. API:et exponerar en valfri delegering som gör att du kan anpassa den underliggande PostgresServerResource-konfigurationen. Du kan till exempel lägga till pgAdmin och pgWeb, lägga till en datavolym- eller databindningsmontering och lägga till en init-bindningsmontering. För mer information, se avsnittet .NET AspirePostgreSQL om värdintegrering.

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 apphosten, och metoden WithPasswordAuthentication anropas för att konfigurera AzurePostgreSQL-servern att använda lösenordsautentisering. Mer information finns i externa parametrar.

Client integration

Kom igång med .NET AspirePostgreSQL-klientintegrering genom att installera 📦Aspire. Npgsql NuGet-paket i det klientkrävande projektet, dvs. projektet för det program 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.Npgsql

Lägg till Npgsql-klient

I Program.cs-filen för projektet som använder klienten anropar du AddNpgsqlDataSource-tilläggsmetoden på valfri IHostApplicationBuilder för att registrera en NpgsqlDataSource så att den kan användas via beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till PostgreSQL-serverresursen i appvärdprojektet. För mer information, se Lägg till PostgreSQL serverresurs.

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

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

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("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

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

Konfiguration

Den .NET AspirePostgreSQL integreringen innehåller flera konfigurationsmetoder och alternativ för att uppfylla kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings-konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar metoden AddNpgsqlDataSource:

builder.AddNpgsqlDataSource("postgresdb");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Mer information finns i ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire-PostgreSQL-integreringen har stöd för Microsoft.Extensions.Configuration. Den läser in NpgsqlSettings från appsettings.json eller andra konfigurationsfiler med hjälp av Aspire:Npgsql-nyckeln. Exempel appsettings.json som konfigurerar några av alternativen:

I följande exempel visas en appsettings.json fil som konfigurerar några av de tillgängliga alternativen:

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

Det fullständiga PostgreSQL klientintegreringsschemat JSON finns i Aspire. Npgsql/ConfigurationSchema.json.

Använd inline-delegeringar

Du kan också vidarebefordra Action<NpgsqlSettings> configureSettings delegat för att konfigurera vissa eller alla alternativ direkt, till exempel för att inaktivera hälsokontrollerna.

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

Client hälsokontroller för integrering

Som standardinställning har .NET.NET Aspireklientintegrationerhälsokontroller aktiverade för alla tjänster. På samma sätt aktiverar många värdintegrationer också slutpunkter för hälsokontroll. Mer information finns i:

  • 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

.NET .NET 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 översikten över .NET.NET Aspire 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

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

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

Spårning

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

  • Npgsql

Mätvärden

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

Lägg till Azure autentiserad Npgsql-klient

Som standard, när du anropar AddAzurePostgresFlexibleServer i din PostgreSQL värdintegrering, konfigureras 📦Azure.Identity NuGet-paket för att aktivera autentisering:

dotnet add package Azure.Identity

Den PostgreSQL anslutningen kan användas via klientintegration och 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));
});

Föregående kodfragment visar hur du använder klassen DefaultAzureCredential från Azure.Identity-paketet för att autentisera med Microsoft Entra-ID och hämta en token för att ansluta till PostgreSQL-databasen. Metoden UsePeriodicPasswordProvider används för att tillhandahålla tokenet till anslutningssträngsbyggaren.

Se även