Dela via

.NET Aspire Azure PostgreSQL Entity Framework Core integrering

  • Artikel

omfattar:Som värd för integrering och Client 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 .NET AspireAzurePostgreSQL kan du ansluta till befintliga AzurePostgreSQL databaser eller skapa nya instanser från .NET med docker.io/library/postgres containeravbildningen.

Värdtjänstintegration

.NET Aspire Azure PostgreSQL som är värd för integrering 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:

Om du vill komma åt dessa typer och API:er för att uttrycka dem som resurser i ditt appvä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 har ett beroende av 📦Aspire.Hosting,PostgreSQL NuGet-paketet, och utökar det till 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. För mer information, se Lokal tillhandahållande: Konfiguration.

Genererad provisionering 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, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app genereras den skapade Bicep-filen tillsammans med manifestfilen. När du lägger till en AzurePostgreSQL resurs genereras följande Bicep:


Växla 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}'

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 är en startpunkt och kan anpassas för att uppfylla dina specifika krav.

Anpassa etableringsinfrastruktur

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

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. Mer information finns i Azure. Anpassning av tillhandahållande.

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

Anteckning

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 matar in den här anslutningssträngen som en miljövariabel i alla beroende resurser, 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:t exponerar en valfri delegering som gör det möjligt för dig att anpassa den underliggande PostgresServerResource-konfigurationen, till exempel genom att lägga till pgAdmin, pgWeb, en datavolym eller en databindning, samt en init-bindning. 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 appvärden, och metoden WithPasswordAuthentication anropas för att konfigurera AzurePostgreSQL-servern till att använda lösenordsautentisering. Mer information finns i externa parametrar.

Client integrering

Kom igång med .NET AspirePostgreSQLEntity Framework Core-klientintegrering genom att installera 📦Aspire. Npgsql.EntityFrameworkCore.PostgreSQL NuGet-paket i det klientkrävande projektet, det vill: projektet för det program som använder PostgreSQL-klienten. .NET 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.Npgsql.EntityFrameworkCore.PostgreSQL

Lägg till npgsql-databaskontext

I den Program.cs filen för ditt kundanvändande projekt, anropar du AddNpgsqlDbContext-tilläggsmetoden på valfri IHostApplicationBuilder för att registrera din DbContext-underklass för användning via containern för beroendeinjektion. Metoden tar en parameter för anslutningsnamn.

builder.AddNpgsqlDbContext<YourDbContext>(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 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.

Lägga till Npgsql-databaskontext med berikning

Om du vill utöka DbContext med ytterligare tjänster, till exempel automatiska återförsök, hälsokontroller, loggning och telemetri, anropar du metoden EnrichNpgsqlDbContext:

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

Parametern settings är en instans av klassen NpgsqlEntityFrameworkCorePostgreSQLSettings.

Konfiguration

Den .NET AspirePostgreSQLEntity Framework Core 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 anger du namnet på anslutningssträngen när du anropar metoden AddNpgsqlDbContext:

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

Anslutningssträngen hämtas från avsnittet ConnectionStrings konfiguration:

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

EnrichNpgsqlDbContext använder inte ConnectionStrings-konfigurationsavsnittet eftersom det förväntar sig att en DbContext registreras vid den tidpunkt då den anropas.

Mer information finns i ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire PostgreSQL Entity Framework Core-integreringen stöder Microsoft.Extensions.Configuration. Den läser in NpgsqlEntityFrameworkCorePostgreSQLSettings från konfigurationsfiler som appsettings.json med hjälp av Aspire:Npgsql:EntityFrameworkCore:PostgreSQL-nyckeln. Om du har konfigurerat konfigurationerna i avsnittet Aspire:Npgsql:EntityFrameworkCore:PostgreSQL kan du bara anropa metoden utan att skicka någon parameter.

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

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

Det fullständiga PostgreSQLEntity Framework Core klientintegreringsschemat JSON finns i Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Använda inline-delegater

Du kan också använda Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> delegera för att konfigurera vissa eller alla alternativ i linje, till exempel för att ange ConnectionString:

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

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.AddNpgsqlDbContext<AnotherDbContext>();

Hälsokontroller

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Som standard hanterar .NET 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

.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 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 .NET AspirePostgreSQLEntity Framework Core genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

  • Npgsql

Mått

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

Lägg till Azure autentiserad Npgsql-klient

När du anropar AddAzurePostgresFlexibleServer i din PostgreSQL värdintegrering kräver det som standard 📦Azure. Identitet NuGet-paket för att aktivera autentisering:

dotnet add package Azure.Identity

Anslutningen PostgreSQL kan användas med hjälp av klientintegration och 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));
});

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 token till anslutningssträngsbyggaren.

Se även