Sdílet prostřednictvím

integrace .NET AspireAzurePostgreSQLEntity Framework Core

  • Článek

zahrnuje:integrace hostování a Client integrace

Azure Database for PostgreSQL– flexibilní Server je relační databázová služba založená na opensourcovém databázovém stroji Postgres. Jedná se o plně spravovanou databázi jako službu, která dokáže zpracovávat důležité úlohy s předvídatelným výkonem, zabezpečením, vysokou dostupností a dynamickou škálovatelností. Integrace .NET AspireAzurePostgreSQL poskytuje způsob, jak se připojit k existujícím databázím AzurePostgreSQL nebo vytvořit nové instance z .NET pomocí image kontejnerudocker.io/library/postgres .

Integrace hostování

.NET Aspire Azure PostgreSQL hostování integrace modeluje flexibilní server a databázi PostgreSQL jako typy AzurePostgresFlexibleServerResource a AzurePostgresFlexibleServerDatabaseResource. Další typy, které jsou ze své podstaty dostupné v integraci hostování, jsou reprezentovány v následujících prostředcích:

Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření jako prostředků v projektu hostitele aplikace , nainstalujte 📦Aspire.Hosting.Azure.PostgreSQL balíček NuGet:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Další informace najdete v tématu dotnet add package.

Integrace hostování AzurePostgreSQL závisí na balíčku NuGet 📦Aspire.Hostování.PostgreSQL a rozšiřuje jej pro podporu Azure. Všechno, co můžete dělat s integrací .NET AspirePostgreSQL a integrací .NET AspirePostgreSQLEntity Framework Core, s touto integrací můžete také provádět.

Přidání prostředku serveru AzurePostgreSQL

Po instalaci integrace hostování .NET AspireAzurePostgreSQL volejte metodu rozšíření AddAzurePostgresFlexibleServer v hostitelském projektu aplikace:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Předchozí volání AddAzurePostgresFlexibleServer nakonfiguruje prostředek serveru PostgreSQL tak, aby byl nasazen jako flexibilní AzurePostgresServer.

Důležitý

Ve výchozím nastavení AddAzurePostgresFlexibleServer konfiguruje ověřování ID Microsoft Entra. To vyžaduje změny aplikací, které se k těmto prostředkům potřebují připojit. Další informace najdete v tématu Client integrace.

Spropitné

Když voláte AddAzurePostgresFlexibleServer, implicitně to volá AddAzureProvisioning, což přidává podporu pro dynamické generování prostředků Azure během spuštění aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Další informace naleznete v tématu Místní zřizování: Konfigurace.

Generované zřizování pomocí Bicep

Pokud s Bicepzačínáte, jedná se o doménově specifický jazyk pro definování Azure prostředků. S .NET.NET Aspirenemusíte psát Bicep ručně, místo toho rozhraní API pro zřizování generuje Bicep za vás. Když publikujete aplikaci, vygenerovaný Bicep se výstupuje spolu se souborem manifestu. Když přidáte prostředek AzurePostgreSQL, vygeneruje se následující Bicep:


Přepněte 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}'

Dříve uvedený modul Bicep zřizuje flexibilní server AzurePostgreSQL s následujícími výchozími nastaveními:

  • authConfig: Konfigurace ověřování serveru PostgreSQL. Výchozí hodnota je ActiveDirectoryAuth povolená a PasswordAuth zakázaná.
  • availabilityZone: Zóna dostupnosti serveru PostgreSQL. Výchozí hodnota je 1.
  • backup: Konfigurace zálohování serveru PostgreSQL. Výchozí hodnota je BackupRetentionDays nastavená na 7 a GeoRedundantBackup nastavená na Disabled.
  • highAvailability: Konfigurace vysoké dostupnosti serveru PostgreSQL. Výchozí hodnota je Disabled.
  • storage: Konfigurace úložiště serveru PostgreSQL. Výchozí hodnota je StorageSizeGB nastavená na 32.
  • version: Verze serveru PostgreSQL. Výchozí hodnota je 16.
  • sku: Skladová položka serveru PostgreSQL. Výchozí hodnota je Standard_B1ms.
  • tags: Značky serveru PostgreSQL. Výchozí hodnota je aspire-resource-name nastavena na název zdroje Aspire, v tomto případě postgres-flexible.

Kromě PostgreSQL flexibilního serveru také zřídí pravidlo brány firewall Azure, které povolí všechny IP adresy Azure. Nakonec se pro server PostgreSQL vytvoří správce a připojovací řetězec se vypíše jako výstupní proměnná. Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury zřizování

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicep tím, že poskytuje plynulé rozhraní API pro konfiguraci Azure prostředků pomocí rozhraní ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API. Můžete například nakonfigurovat kind, consistencyPolicy, locationsatd. Následující příklad ukazuje, jak přizpůsobit zdroj AzureAzure Cosmos DB:

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

Předchozí kód:

K dispozici je mnoho dalších možností konfigurace pro přizpůsobení prostředku flexibilního serveru PostgreSQL. Další informace najdete v tématu Azure.Provisioning.PostgreSql. Další informace najdete v tématu Azure. Přizpůsobení zřizování.

Připojení k existujícímu flexibilnímu serveru AzurePostgreSQL

Možná máte existující AzurePostgreSQL flexibilní server, ke kterému se chcete připojit. Místo toho, abyste představovali nový prostředek flexibilního serveru AzurePostgreSQL, můžete k hostiteli aplikace přidat připojovací řetězec. Pokud chcete přidat připojení k existujícímu AzurePostgreSQL flexibilnímu serveru, zavolejte metodu 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...

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace vloží tento připojovací řetězec jako proměnnou prostředí do všech závislých prostředků, například:

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

Voláním metody GetConnectionString a tím, že předáte název připojení jako parametr, získá závislý prostředek přístup k vloženému připojovacímu řetězci, v tomto případě "postgres". Rozhraní API GetConnectionString je zkrácené označení pro IConfiguration.GetSection("ConnectionStrings")[name].

Spuštění prostředku AzurePostgreSQL ve formě kontejneru

Integrace hostování AzurePostgreSQL podporuje spuštění serveru PostgreSQL jako místního kontejneru. To je užitečné v situacích, kdy chcete spustit PostgreSQL server místně pro účely vývoje a testování, abyste se vyhnuli nutnosti zřídit Azure prostředek nebo se připojit k existujícímu serveru AzurePostgreSQL.

Pokud chcete spustit PostgreSQL server jako kontejner, zavolejte metodu 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);

Předchozí kód nakonfiguruje prostředek AzurePostgreSQL Flexibilní Server tak, aby běžel místně v kontejneru.

Spropitné

Metoda RunAsContainer je užitečná pro místní vývoj a testování. Rozhraní API zveřejňuje volitelný delegát, který umožňuje přizpůsobit základní konfiguraci PostgresServerResource, jako je přidání nástrojů pgAdmin, pgWeb, datového svazku nebo připojení data bind mount, a také přidání init bind mount. Další informace najdete v části .NET AspirePostgreSQL integračního hostování.

Nakonfigurujte server AzurePostgreSQL tak, aby používal ověřování heslem.

Ve výchozím nastavení je server AzurePostgreSQL nakonfigurovaný tak, aby používal ověřování ověřování Microsoft Entra ID. Pokud chcete použít ověřování heslem, můžete server nakonfigurovat tak, aby používal ověřování heslem zavoláním metody 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);

Předchozí kód nakonfiguruje server AzurePostgreSQL tak, aby používal ověřování heslem. Parametry username a password se přidají do hostitele aplikace jako parametry a volá se metoda WithPasswordAuthentication pro konfiguraci AzurePostgreSQL serveru tak, aby používal ověřování heslem. Další informace naleznete v tématu Externí parametry.

integrace Client

Pokud chcete začít s integrací klienta .NET AspirePostgreSQLEntity Framework Core, nainstalujte balíček NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL do projektu, který spotřebovává klienta, tedy projektu aplikace, která používá klienta PostgreSQL. Integrace klienta .NET AspirePostgreSQLEntity Framework Core registruje požadované instance podtřídy DbContext, které můžete použít k interakci s PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Přidání kontextu databáze Npgsql

V souboru Program.cs projektu, který využívá klienta, zavolejte metodu rozšíření AddNpgsqlDbContext na libovolném IHostApplicationBuilder a zaregistrujte podtřídu DbContext pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

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

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku serveru PostgreSQL v projektu hostitele aplikace. Další informace naleznete v části Přidat serverový prostředek PostgreSQL.

Po přidání YourDbContext do sestavovače můžete získat instanci YourDbContext pomocí injektování závislostí. Pokud například chcete načíst objekt zdroje dat z ukázkové služby, definujte ho jako parametr konstruktoru a ujistěte se, že je třída ExampleService zaregistrovaná v kontejneru injektáže závislostí:

public class ExampleService(YourDbContext context)
{
    // Use context...
}

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání kontextu databáze Npgsql s obohacením

Pokud chcete rozšířit DbContext dalšími službami, jako jsou automatické opakování, kontroly stavu, protokolování a telemetrie, zavolejte metodu EnrichNpgsqlDbContext:

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

Parametr settings je instance třídy NpgsqlEntityFrameworkCorePostgreSQLSettings.

Konfigurace

Integrace .NET AspirePostgreSQLEntity Framework Core poskytuje několik přístupů a možností konfigurace pro splnění požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings zadáte název připojovacího řetězce při volání metody AddNpgsqlDbContext:

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

Připojovací řetězec se načte z oddílu konfigurace ConnectionStrings:

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

EnrichNpgsqlDbContext nepoužije konfigurační oddíl ConnectionStrings, protože očekává, že DbContext bude registrován v okamžiku jeho volání.

Další informace naleznete v ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspirePostgreSQLEntity Framework Core podporuje Microsoft.Extensions.Configuration. Načte NpgsqlEntityFrameworkCorePostgreSQLSettings z konfiguračních souborů, jako je appsettings.json, pomocí klíče Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Pokud jste nastavili konfigurace v oddílu Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, stačí volat metodu bez předání jakéhokoli parametru.

Následující příklad ukazuje soubor appsettings.json, který konfiguruje některé z dostupných možností:

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

Kompletní schéma integrace klienta PostgreSQLEntity Framework CoreJSON naleznete v dokumentaci Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Použijte in-line delegáty

Můžete také předat delegáta Action<NpgsqlEntityFrameworkCorePostgreSQLSettings>, abyste nastavili některé nebo všechny možnosti přímo, například nastavit ConnectionString.

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

Konfigurace více tříd DbContext

Pokud chcete zaregistrovat více než jedno DbContext s různými konfiguracemi, můžete použít název sekce konfigurace $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}". Konfigurace json by vypadala takto:

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

Volání metody AddNpgsqlDbContext s parametrem typu AnotherDbContext by pak načetlo nastavení z oddílu Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Kontroly stavu

Ve výchozím nastavení integrace .NET.NET Aspire umožňují kontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire přehled integrací.

Integrace .NET AspirePostgreSQLEntity Framework Core ve výchozím nastavení zpracovává následující:

  • Přidá DbContextHealthCheck, která volá metodu CanConnectAsyncEF Core. Název kontroly stavu odpovídá typu TContext.
  • Integruje se s /health HTTP koncovým bodem, který určuje, že všechny registrované kontroly stavu musí projít, aby byla aplikace považována za připravenou k přijímání síťového provozu.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspirePostgreSQLEntity Framework Core používá následující kategorie protokolů:

  • 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

Trasování

Integrace .NET AspirePostgreSQLEntity Framework Core pomocí OpenTelemetryvygeneruje následující aktivity trasování:

  • Npgsql

Metričky

Integrace .NET AspirePostgreSQLEntity Framework Core pomocí OpenTelemetryvygeneruje následující metriky:

  • 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

Přidání Azure ověřeného klienta Npgsql

Když ve výchozím nastavení voláte AddAzurePostgresFlexibleServer v integraci hostování PostgreSQL, vyžaduje 📦Azure. Identita balíčku NuGet pro povolení ověřování:

dotnet add package Azure.Identity

Připojení PostgreSQL lze využít pomocí klientské integrace a 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));
});

Předchozí fragment kódu ukazuje použití třídy DefaultAzureCredential z balíčku Azure.Identity k ověření pomocí Microsoft Entra ID a načtení tokenu pro připojení k databázi PostgreSQL. Metoda UsePeriodicPasswordProvider slouží k poskytnutí tokenu sestavovateli připojovacích řetězců.

Viz také