Delen via

Integratie van .NET Aspire,Azure,PostgreSQLenEntity Framework Core

  • Artikel

omvat:hosting-integratie 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 om nieuwe exemplaren vanuit .NET te maken met de docker.io/library/postgres-containerafbeelding.

Hostingintegratie

De .NET AspireAzurePostgreSQL hostintegratiemodellen vormen een PostgreSQL flexibele server en database als de AzurePostgresFlexibleServerResource en AzurePostgresFlexibleServerDatabaseResource typen. 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.Hosting.PostgreSQL NuGet-pakket en breidt het uit om Azurete ondersteunen. Alles wat u kunt doen met de .NET AspirePostgreSQL integratie en .NET AspirePostgreSQLEntity Framework Core integratie, kunt u ook met deze integratie doen.

Voeg serverresource AzurePostgreSQL toe

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 verificatie. 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 voorziening Bicep

Als u nieuw bent met Bicep, dan is het een domeinspecifieke taal voor het definiëren van Azure resources. 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 weergegeven naast het manifestbestand. 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 beheerder gemaakt voor de PostgreSQL-server en wordt de verbindingsreeks uitgegeven als een uitvoervariabele. De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Infrastructuur voor provisioning aanpassen

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep-configuraties aanpassen door een fluente API te bieden om de Azure-resources te configureren, met behulp 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.Voorziening aanpassen.

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 de 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL NuGet-pakket om aan de slag te gaan met de .NET AspirePostgreSQLEntity Framework Core-clientintegratie in het project dat de client gebruikt, dat wil zeggen, het project voor de toepassing die gebruikmaakt van de PostgreSQL-client. De .NET AspirePostgreSQLEntity Framework Core-clientintegratie registreert de gewenste DbContext subklasse-exemplaren die u kunt gebruiken om met PostgreSQLte communiceren.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Npgsql-databasecontext bijwerken

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

builder.AddNpgsqlDbContext<YourDbContext>(connectionName: "postgresdb");

Tip

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 YourDbContext aan de builder hebt toegevoegd, kunt u de YourDbContext 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(YourDbContext context)
{
    // Use context...
}

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Npgsql-databasecontext toevoegen met verrijking

Als u de DbContext wilt verrijken met aanvullende services, zoals automatische herhalingen, statuscontroles, telemetrie en logboekregistratie, roept u de methode EnrichNpgsqlDbContext aan.

builder.EnrichNpgsqlDbContext<YourDbContext>(
    connectionName: "postgresdb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

De parameter settings is een exemplaar van de klasse NpgsqlEntityFrameworkCorePostgreSQLSettings.

Configuratie

De .NET AspirePostgreSQLEntity Framework Core-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, geeft u de naam van de verbindingsreeks op bij het aanroepen van de AddNpgsqlDbContext methode:

builder.AddNpgsqlDbContext<MyDbContext>("pgdb");

De verbindingsreeks wordt opgehaald uit de ConnectionStrings configuratiesectie:

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

De EnrichNpgsqlDbContext maakt geen gebruik van de ConnectionStrings-configuratiesectie, omdat er een DbContext wordt verwacht die moet worden geregistreerd wanneer deze wordt aangeroepen.

Zie de ConnectionStringvoor meer informatie.

Configuratieproviders gebruiken

De .NET AspirePostgreSQLEntity Framework Core-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de NpgsqlEntityFrameworkCorePostgreSQLSettings uit configuratiebestanden zoals appsettings.json met behulp van de Aspire:Npgsql:EntityFrameworkCore:PostgreSQL sleutel. Als u uw configuraties in de sectie Aspire:Npgsql:EntityFrameworkCore:PostgreSQL hebt ingesteld, kunt u de methode gewoon aanroepen zonder een parameter door te geven.

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

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

Voor het volledige PostgreSQLEntity Framework Core clientintegratieschema JSON, zie Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Inline gedelegeerden gebruiken

U kunt de Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> delegate ook doorgeven om alle of een deel van de opties direct in te stellen, bijvoorbeeld om de ConnectionStringte configureren.

builder.AddNpgsqlDbContext<YourDbContext>(
    "pgdb",
    static settings => settings.ConnectionString = "<YOUR CONNECTION STRING>");

Meerdere DbContext-klassen configureren

Als u meer dan één DbContext met een andere configuratie wilt registreren, kunt u $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}" configuratiesectienaam gebruiken. De json-configuratie ziet er als volgt uit:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "<YOUR CONNECTION STRING>",
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "AnotherDbContext": {
            "ConnectionString": "<ANOTHER CONNECTION STRING>",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

Als u vervolgens de methode AddNpgsqlDbContext aanroept met AnotherDbContext typeparameter, worden de instellingen vanuit Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext sectie geladen.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Gezondheidscontroles

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

De .NET AspirePostgreSQLEntity Framework Core-integraties verwerken standaard het volgende:

  • Hiermee wordt de DbContextHealthChecktoegevoegd, waarmee de CanConnectAsync methode van EF Corewordt aangeroepen. De naam van de gezondheidscontrole is de naam van het TContext-type.
  • Integreert met het /health HTTP-eindpunt, waarbij alle geregistreerde gezondheidscontroles moeten slagen zodat de app als klaar wordt beschouwd voor het accepteren van verkeer.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties configureren automatisch logging-, tracing- en metriekinstellingen, die ook wel bekend staan als de pijlers van observability. 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 AspirePostgreSQLEntity Framework Core-integratie maakt gebruik van de volgende logboekcategorieën:

  • Microsoft.EntityFrameworkCore.ChangeTracking
  • Microsoft.EntityFrameworkCore.Database.Command
  • Microsoft.EntityFrameworkCore.Database.Connection
  • Microsoft.EntityFrameworkCore.Database.Transaction
  • Microsoft.EntityFrameworkCore.Migrations
  • Microsoft.EntityFrameworkCore.Infrastructure
  • Microsoft.EntityFrameworkCore.Migrations
  • Microsoft.EntityFrameworkCore.Model
  • Microsoft.EntityFrameworkCore.Model.Validation
  • Microsoft.EntityFrameworkCore.Query
  • Microsoft.EntityFrameworkCore.Update

Opsporing

De integratie van .NET AspirePostgreSQLEntity Framework Core verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

  • Npgsql

Statistieken

De integratie van .NET AspirePostgreSQLEntity Framework Core verzendt de volgende metrische gegevens met behulp van OpenTelemetry:

  • Microsoft.EntityFrameworkCore:

    • ec_Microsoft_EntityFrameworkCore_active_db_contexts
    • ec_Microsoft_EntityFrameworkCore_total_queries
    • ec_Microsoft_EntityFrameworkCore_queries_per_second
    • ec_Microsoft_EntityFrameworkCore_total_save_changes
    • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
    • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
    • ec_Microsoft_Entity_total_execution_strategy_operation_failures
    • ec_Microsoft_E_execution_strategy_operation_failures_per_second
    • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
    • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

  • 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 vereist het aanroepen van AddAzurePostgresFlexibleServer in uw PostgreSQL hostingintegratie het 📦Azure.Identity NuGet-pakket om verificatie in te schakelen.

dotnet add package Azure.Identity

De PostgreSQL-verbinding kan worden gebruikt met behulp van de clientintegratie en Azure.Identity:

builder.AddNpgsqlDbContext<YourDbContext>(
    "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 builder voor verbindingsreeks op te geven.

Zie ook