Aspire Azure PostgreSQL Entity Framework Core integration

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.

Värdtjänstintegration

Aspire Azure PostgreSQL värdintegrationen modellerar en PostgreSQL flexibel server och databas som AzurePostgresFlexibleServerResource- och AzurePostgresFlexibleServerDatabaseResource-typer. 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 har ett beroende av 📦Aspire.Hosting,PostgreSQL NuGet-paketet, och utökar det till 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 infrastruktur för provisionering

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.
  • Det 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 AspirePostgreSQLEntity Framework Core genom att 📦Aspireinstallera .Azure. Npgsql.EntityFrameworkCore.PostgreSQL NuGet-paket i det klientkrävande projektet, det vill s.v.s. projektet för det program som använder PostgreSQL klienten. Aspire PostgreSQL Entity Framework Core-klientintegrering registrerar önskade DbContext underklassinstanser som du kan använda för att interagera med PostgreSQL.

dotnet add package Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL

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

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

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

Föregående kodfragment visar hur du använder AddAzureNpgsqlDbContext metoden för att registrera en YourDbContext instans (som är poolad för prestanda) 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 YourDbContext i byggaren kan du hämta YourDbContext-instansen med hjälp av 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(YourDbContext context)
{
    // Use context...
}

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Utöka en Npgsql-databaskontext

Du kanske föredrar att använda entitetsramverkets standardmetod för att hämta en databaskontext och lägga till den i containern för beroendeinmatning:

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));

Du har större flexibilitet när du skapar databaskontexten på det här sättet, till exempel:

• Du kan återanvända befintlig konfigurationskod för databaskontexten utan att skriva om den för Aspire.
• Du kan använda Entity Framework Core interceptorer för att ändra databasåtgärder.
• Du kan välja att inte använda Entity Framework Core kontextpooler, vilket kan fungera bättre under vissa omständigheter.

Om du använder den här metoden kan du förbättra databaskontexten med Aspire återförsök, hälsokontroller, loggning och telemetrifunktioner genom att anropa EnrichAzureNpgsqlDbContext metoden:

builder.EnrichAzureNpgsqlDbContext<YourDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30;
    });

Parametern settings är en instans av klassen AzureNpgsqlEntityFrameworkCorePostgreSQLSettings.

Du kan också behöva konfigurera specifika alternativ för Npgsql eller registrera ett DbContext på andra sätt. I det här fallet gör du det genom att anropa EnrichAzureNpgsqlDbContext tilläggsmetoden, som du ser i följande exempel:

var connectionString = builder.Configuration.GetConnectionString("postgresdb");

builder.Services.AddDbContextPool<YourDbContext>(
    dbContextOptionsBuilder => dbContextOptionsBuilder.UseNpgsql(connectionString));

builder.EnrichAzureNpgsqlDbContext<YourDbContext>();

Konfiguration

EntityFrameworkCore AspireAzurePostgreSQL 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.AddAzureNpgsqlDbContext<YourDbContext>("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

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

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

Använda inline-delegater

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

builder.AddAzureNpgsqlDbContext<YourDbContext>(
    "postgresdb",
    settings => settings.DisableHealthChecks = true);

Du kan också använda EnrichAzureNpgsqlDbContext tilläggsmetoden för att konfigurera inställningarna:

builder.EnrichAzureNpgsqlDbContext<YourDbContext>(
    settings => settings.DisableHealthChecks = true);

Använd egenskapen AzureNpgsqlEntityFrameworkCorePostgreSQLSettings.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.

Felsökning

I det sällsynta fallet att Username egenskapen inte tillhandahålls och integreringen inte kan identifiera den med programmets hanterade identitet, utlöser Npgsql ett undantag med ett meddelande som liknar följande:

Npgsql.PostgresException (0x80004005): 28P01: lösenordsautentiseringen misslyckades för användaren ...

I det här fallet kan du konfigurera Username egenskapen i anslutningssträngen och använda EnrichAzureNpgsqlDbContextoch skicka anslutningssträngen i UseNpgsql:

builder.Services.AddDbContextPool<YourDbContext>(
    options => options.UseNpgsql(newConnectionString));

builder.EnrichAzureNpgsqlDbContext<YourDbContext>();

Konfigurera flera DbContext-klasser

Om du vill registrera fler än en DbContext med en annan konfiguration kan du använda $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}" namn på konfigurationsavsnittet. Json-konfigurationen skulle se ut så här:

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

Om du sedan anropar AddNpgsqlDbContext-metoden med parametern AnotherDbContext typ läser du in inställningarna från Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext avsnittet.

builder.AddAzureNpgsqlDbContext<AnotherDbContext>();

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

Som standard hanterar AspirePostgreSQLEntity Framework Core-integreringarna följande:

• Lägger till DbContextHealthCheck, som anropar EF Core:s CanConnectAsync-metoden. Namnet på hälsokontrollen är namnet på typen TContext.
• Integrerar med /health HTTP-slutpunkt, som specificerar att alla registrerade hälsokontroller måste passera för att appen ska anses redo att ta emot 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 Entity Framework Core-integreringen använder följande loggkategorier:

• 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

Spårning

Integreringen AspirePostgreSQLEntity Framework Core genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• Npgsql

Mått

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

Se även

• PostgreSQL Docs
• Azure Databas för PostgreSQL
• Aspire PostgreSQL Entity Framework Core integrering
• Aspire Integrationer
• Aspire GitHub Repo