Delen via

integratie van .NET AspireAzurePostgreSQL

  • Artikel

omvat:hostingintegratie en Client integratie

Azure Database for PostgreSQL— Flexible Server is een relationele databaseservice op basis van de opensource-Postgres database-engine. Het is een volledig beheerde database-as-a-service die bedrijfskritieke workloads kan verwerken met voorspelbare prestaties, beveiliging, hoge beschikbaarheid en dynamische schaalbaarheid. De .NET AspireAzurePostgreSQL-integratie biedt een manier om verbinding te maken met bestaande AzurePostgreSQL-databases of nieuwe exemplaren te maken vanuit .NET met de docker.io/library/postgres-containerafbeelding.

Hostingintegratie

De .NET AspireAzurePostgreSQL hostintegratiemodellen modelleren een flexibele PostgreSQL-server en database als de typen AzurePostgresFlexibleServerResource en AzurePostgresFlexibleServerDatabaseResource. Andere typen die inherent beschikbaar zijn in de hostingintegratie, worden weergegeven in de volgende resources:

Als u toegang wilt krijgen tot deze typen en API's om ze uit te drukken als resources in uw app-host-project, installeert u het 📦Aspire.Hosting.Azure.PostgreSQL NuGet-pakket:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Zie dotnet add packagevoor meer informatie.

De AzurePostgreSQL hostingintegratie heeft een afhankelijkheid van het 📦Aspire.HostingPostgreSQL NuGet-pakket, en breidt het uit om ondersteuning voor Azurete bieden. Alles wat u kunt doen met de .NET AspirePostgreSQL integratie en de .NET AspirePostgreSQLEntity Framework Core integratie, kunt u ook met deze integratie doen.

Azure PostgreSQL serverbron toevoegen

Nadat u de .NET AspireAzurePostgreSQL hostingintegratie hebt geïnstalleerd, roept u de AddAzurePostgresFlexibleServer-extensiemethode aan in uw app-hostproject:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Met de voorgaande aanroep voor AddAzurePostgresFlexibleServer configureert u de PostgresSQL-serverresource die moet worden geïmplementeerd als een AzurePostgres Flexible Server.

Belangrijk

Standaard configureert AddAzurePostgresFlexibleServerMicrosoft Entra ID authenticatie. Hiervoor moeten wijzigingen worden aangebracht in toepassingen die verbinding moeten maken met deze resources. Zie Client integratievoor meer informatie.

Fooi

Wanneer u AddAzurePostgresFlexibleServeraanroept, wordt impliciet AddAzureProvisioningaangeroepen. Hiermee wordt ondersteuning toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokale inrichting: Configuratievoor meer informatie.

Gegenereerde inrichting Bicep

Als je nieuw bent bij Bicep, het is een domeinspecifieke taal voor het definiëren van Azure bronnen. Met .NET.NET Aspirehoeft u bicep niet handmatig te schrijven, in plaats daarvan genereren de inrichtings-API's Bicep voor u. Wanneer u uw app publiceert, wordt de gegenereerde Bicep samen met het manifestbestand weergegeven. Wanneer u een AzurePostgreSQL resource toevoegt, wordt de volgende Bicep gegenereerd:


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

De voorgaande Bicep is een module die een AzurePostgreSQL flexibele server in richt met de volgende standaardwaarden:

  • authConfig: de verificatieconfiguratie van de PostgreSQL-server. De standaardwaarde is ActiveDirectoryAuth ingeschakeld en PasswordAuth uitgeschakeld.
  • availabilityZone: de beschikbaarheidszone van de PostgreSQL-server. De standaardwaarde is 1.
  • backup: de back-upconfiguratie van de PostgreSQL-server. De standaardwaarde is BackupRetentionDays ingesteld op 7 en GeoRedundantBackup ingesteld op Disabled.
  • highAvailability: de configuratie van hoge beschikbaarheid van de PostgreSQL-server. De standaardwaarde is Disabled.
  • storage: de opslagconfiguratie van de PostgreSQL-server. De standaardwaarde is StorageSizeGB ingesteld op 32.
  • version: de versie van de PostgreSQL-server. De standaardwaarde is 16.
  • sku: de SKU van de PostgreSQL-server. De standaardwaarde is Standard_B1ms.
  • tags: de tags van de PostgreSQL-server. De standaardwaarde is aspire-resource-name ingesteld op de naam van de Aspire-resource, in dit geval postgres-flexible.

Naast de PostgreSQL flexibele server wordt er ook een Azure firewallregel ingesteld om alle Azure IP-adressen toe te staan. Ten slotte wordt er een administrator gemaakt voor de PostgreSQL-server en wordt de connection string uitgegeven als uitvoervariabele. De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Voorzieningsinfrastructuur aanpassen

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen door middel van een fluente API om de Azure-resources te configureren, gebruikmakend van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. U kunt bijvoorbeeld de kind, consistencyPolicy, locationsen meer configureren. In het volgende voorbeeld ziet u hoe u de AzureAzure Cosmos DB-resource aanpast:

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

De voorgaande code:

Er zijn nog veel meer configuratieopties beschikbaar om de PostgreSQL flexibele serverresource aan te passen. Zie Azure.Provisioning.PostgreSqlvoor meer informatie. Zie Azurevoor meer informatie over het aanpassen van voorzieningen.

Verbinding maken met een bestaande AzurePostgreSQL flexibele server

Mogelijk hebt u een bestaande AzurePostgreSQL flexibele server waarmee u verbinding wilt maken. In plaats van een nieuwe AzurePostgreSQL flexibele serverresource weer te geven, kunt u een verbindingsreeks toevoegen aan de app-host. Als u een verbinding wilt toevoegen aan een bestaande AzurePostgreSQL flexibele server, roept u de methode AddConnectionString aan:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

De verbindingsreeks is geconfigureerd in de configuratie van de app-host, meestal onder gebruikersgeheimen, onder de sectie ConnectionStrings. De app-host injecteert deze verbindingsreeks als een omgevingsvariabele in alle afhankelijke resources, bijvoorbeeld:

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

De afhankelijke resource heeft toegang tot de geïnjecteerde verbindingsreeks door de methode GetConnectionString aan te roepen en de verbindingsnaam door te geven als de parameter, in dit geval "postgres". De GetConnectionString-API is een afkorting voor IConfiguration.GetSection("ConnectionStrings")[name].

Azure PostgreSQL-resource uitvoeren als een container

De AzurePostgreSQL hostingintegratie ondersteunt het uitvoeren van de PostgreSQL-server als een lokale container. Dit is handig voor situaties waarin u de PostgreSQL-server lokaal wilt uitvoeren voor ontwikkelings- en testdoeleinden, zodat u geen Azure resource hoeft in te richten of verbinding wilt maken met een bestaande AzurePostgreSQL-server.

Als u de PostgreSQL-server als een container wilt uitvoeren, roept u de RunAsContainer-methode aan:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Met de voorgaande code wordt een AzurePostgreSQL Flexible Server-resource geconfigureerd om lokaal in een container te worden uitgevoerd.

Tip

De RunAsContainer methode is handig voor lokale ontwikkeling en testen. De API bevat een optionele gemachtigde waarmee u de onderliggende PostgresServerResource-configuratie kunt aanpassen, zoals pgAdmin, pgWeb toevoegen, een gegevensvolume of koppeling voor gegevensbinding toevoegen en een init-bindingskoppeling toevoegen. Zie de sectie .NET AspirePostgreSQL hostingintegratie voor meer informatie.

De AzurePostgreSQL-server configureren voor wachtwoordverificatie

De AzurePostgreSQL-server is standaard geconfigureerd voor het gebruik van Microsoft Entra ID verificatie. Als u wachtwoordverificatie wilt gebruiken, kunt u de server configureren voor wachtwoordverificatie door de WithPasswordAuthentication methode aan te roepen:

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

Met de voorgaande code wordt de AzurePostgreSQL-server geconfigureerd voor het gebruik van wachtwoordverificatie. De parameters username en password worden als parameters aan de app-host toegevoegd en de methode WithPasswordAuthentication wordt aangeroepen om de AzurePostgreSQL-server te configureren voor het gebruik van wachtwoordverificatie. Zie Externe parametersvoor meer informatie.

integratie van Client

Installeer het 📦Aspire.Npgsql NuGet-pakket in het project voor de toepassing die de PostgreSQL-client gebruikt om aan de slag te gaan met de .NET AspirePostgreSQL-clientintegratie. De PostgreSQL-clientintegratie registreert een NpgsqlDataSource--exemplaar dat u kunt gebruiken om met PostgreSQLte communiceren.

dotnet add package Aspire.Npgsql

Npgsql-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddNpgsqlDataSource-extensiemethode aan op elke IHostApplicationBuilder om een NpgsqlDataSource te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Fooi

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de PostgreSQL serverresource in het hostproject van de app. Zie PostgreSQL serverresource toevoegenvoor meer informatie.

Nadat u NpgsqlDataSource aan de builder hebt toegevoegd, kunt u de NpgsqlDataSource instantie ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld uw gegevensbronobject wilt ophalen uit een voorbeeldservice, definieert u het als een constructorparameter en zorgt u ervoor dat de klasse ExampleService is geregistreerd bij de container voor afhankelijkheidsinjectie:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Geëigende Npgsql-client toevoegen

Er kunnen situaties zijn waarin u meerdere NpgsqlDataSource exemplaren met verschillende verbindingsnamen wilt registreren. Als u keyed Npgsql-clients wilt registreren, roept u de methode AddKeyedNpgsqlDataSource aan:

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

Vervolgens kunt u de NpgsqlDataSource instanties ophalen via afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over sleutelservices, zie .NET afhankelijkheidsinjectie: Keyed Services.

Configuratie

De .NET AspirePostgreSQL-integratie biedt meerdere configuratiemethoden en opties om te voldoen aan de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van de AddNpgsqlDataSource methode:

builder.AddNpgsqlDataSource("postgresdb");

Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings configuratiesectie:

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

Zie de ConnectionStringvoor meer informatie.

Configuratieproviders gebruiken

De .NET AspirePostgreSQL-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de NpgsqlSettings uit appsettings.json of andere configuratiebestanden met behulp van de Aspire:Npgsql-sleutel. Voorbeeld appsettings.json waarmee een aantal van de opties wordt geconfigureerd:

In het volgende voorbeeld ziet u een appsettings.json-bestand waarmee een aantal van de beschikbare opties wordt geconfigureerd:

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

Voor het volledige PostgreSQL clientintegratieschema JSON, zie Aspire. Npgsql/ConfigurationSchema.json.

Gebruik inline delegeren

U kunt ook de Action<NpgsqlSettings> configureSettings gedelegeerde doorgeven om bepaalde of alle opties inline in te stellen, bijvoorbeeld om gezondheidscontroles uit te schakelen.

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

Gezondheidscontroles

Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

  • Voegt de NpgSqlHealthChecktoe, waarmee wordt gecontroleerd of opdrachten kunnen worden uitgevoerd op basis van de onderliggende Postgres-database.
  • Kan worden geïntegreerd met het /health HTTP-eindpunt, waarbij alle geregistreerde gezondheidscontroles moeten slagen zodat de app gereed wordt geacht om verkeer te accepteren.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties automatisch configuraties voor logboekregistratie, tracering en metrische gegevens instellen, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Logboekregistratie

De .NET AspirePostgreSQL-integratie maakt gebruik van de volgende logboekcategorieën:

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

Tracering

De .NET AspirePostgreSQL-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

  • Npgsql

Statistieken

De integratie van .NET AspirePostgreSQL verzendt de volgende metrische gegevens met behulp van 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

Geverifieerde Npgsql-client toevoegen Azure

Standaard wordt, wanneer u AddAzurePostgresFlexibleServer aanroept in uw PostgreSQL hostingintegratie, het 📦Azure.Identity NuGet-pakket geconfigureerd om authenticatie in te schakelen.

dotnet add package Azure.Identity

De PostgreSQL-verbinding kun je gebruiken met behulp van de clientintegratie en 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));
});

Het voorgaande codefragment laat zien hoe u de DefaultAzureCredential-klasse uit het Azure.Identity-pakket gebruikt om te verifiëren met Microsoft Entra ID en een token ophaalt om verbinding te maken met de PostgreSQL-database. De methode UsePeriodicPasswordProvider wordt gebruikt om het token aan de verbindingsreeks-bouwer te leveren.

Zie ook