Udostępnij za pośrednictwem

integracja .NET AspireAzurePostgreSQL

  • Artykuł

obejmuje: integracja hostingu oraz integracja Client

Azure Database for PostgreSQL— elastyczny Server to usługa relacyjnej bazy danych oparta na open-source'owym silniku bazy danych Postgres. Jest to w pełni zarządzana baza danych jako usługa, która może obsługiwać obciążenia o krytycznym znaczeniu z przewidywalną wydajnością, zabezpieczeniami, wysoką dostępnością i dynamiczną skalowalnością. Integracja .NET AspireAzurePostgreSQL umożliwia łączenie się z istniejącymi bazami danych AzurePostgreSQL lub tworzenie nowych wystąpień z .NET przy użyciu obrazu kontenera docker.io/library/postgres.

Integracja hostingu

.NET Aspire Azure PostgreSQL integracja hostowania modeluje PostgreSQL elastyczny serwer i bazę danych jako typy AzurePostgresFlexibleServerResource i AzurePostgresFlexibleServerDatabaseResource. Inne typy, które są z natury dostępne w integracji hostingu, są reprezentowane w następujących zasobach:

Aby uzyskać dostęp do tych typów i interfejsów API w celu wyrażenia ich jako zasobów w projekcie hosta aplikacji , zainstaluj pakiet 📦Aspire.Hosting.Azure.PostgreSQL NuGet.

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Więcej informacji znajdziesz w dotnet add package.

Integracja hostowania AzurePostgreSQL zależy od pakietu NuGet 📦Aspire.Hosting.PostgreSQL, rozszerzając go w celu obsługi Azure. Wszystko, co można zrobić za pomocą integracji .NET AspirePostgreSQL i integracji .NET AspirePostgreSQLEntity Framework Core można również wykonać z tą integracją.

Dodawanie zasobu serwera AzurePostgreSQL

Po zainstalowaniu integracji hostingu .NET AspireAzurePostgreSQL wywołaj metodę rozszerzenia AddAzurePostgresFlexibleServer w projekcie hostującym aplikację.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Poprzednie wywołanie AddAzurePostgresFlexibleServer konfiguruje zasób serwera PostgreSQL do wdrożenia jako elastyczny AzurePostgresServer.

Ważny

Domyślnie AddAzurePostgresFlexibleServer konfiguruje uwierzytelnianie Identyfikator entra firmy Microsoft. Wymaga to zmian w aplikacjach, które muszą łączyć się z tymi zasobami. Aby uzyskać więcej informacji, zobacz Client integration.

Napiwek

Podczas wywołania AddAzurePostgresFlexibleServernastępuje również niejawne wywołanie AddAzureProvisioning, co dodaje możliwość dynamicznego generowania zasobów Azure podczas uruchamiania aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Lokalna konfiguracja: Konfiguracja.

Wygenerowane prowizjonowanie Bicep

Jeśli dopiero zaczynasz z Bicep, to jest język specyficzny dla domeny służący do definiowania zasobów Azure. W przypadku .NET.NET Aspirenie musisz pisać Bicep ręcznie, zamiast tego interfejsy API aprowizacji generują Bicep. Podczas publikowania aplikacji wygenerowany Bicep jest wyświetlany wraz z plikiem manifestu. Po dodaniu zasobu AzurePostgreSQL zostanie wygenerowany następujący Bicep:


przełącz AzurePostgreSQL Biceps. 

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

Poprzedni Bicep jest modułem, który konfiguruje elastyczny serwer AzurePostgreSQL z następującymi wartościami domyślnymi:

  • authConfig: konfiguracja uwierzytelniania serwera PostgreSQL. Wartość domyślna to ActiveDirectoryAuth włączona i PasswordAuth wyłączona.
  • availabilityZone: strefa dostępności serwera PostgreSQL. Wartość domyślna to 1.
  • backup: konfiguracja kopii zapasowej serwera PostgreSQL. Wartość domyślna to BackupRetentionDays ustawiona na 7 i GeoRedundantBackup ustawiona na wartość Disabled.
  • highAvailability: konfiguracja wysokiej dostępności serwera PostgreSQL. Wartość domyślna to Disabled.
  • storage: konfiguracja pamięci masowej serwera PostgreSQL. Wartość domyślna to StorageSizeGB ustawiona na wartość 32.
  • version: wersja serwera PostgreSQL. Wartość domyślna to 16.
  • sku: jednostka SKU serwera PostgreSQL. Wartość domyślna to Standard_B1ms.
  • tags: tagi serwera PostgreSQL. Wartość domyślna to aspire-resource-name ustawiona na nazwę zasobu Aspire, w tym przypadku postgres-flexible.

Oprócz elastycznego serwera PostgreSQL, konfiguruje również regułę zapory Azure, która zezwala na wszystkie adresy IP Azure. Na koniec dla serwera PostgreSQL jest tworzony administrator, a parametry połączenia są zwracane jako zmienna wyjściowa. Wygenerowany Bicep jest punktem wyjścia i można go dostosować, aby spełnić określone wymagania.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego pliku Bicep poprzez zapewnienie płynnego interfejsu API do konfigurowania zasobów Azure przy użyciu interfejsu API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Można na przykład skonfigurować kind, consistencyPolicy, locationsi więcej. W poniższym przykładzie pokazano, jak dostosować zasób 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");
    });

Powyższy kod:

Dostępnych jest wiele opcji konfiguracji umożliwiających dostosowanie PostgreSQL zasobu serwera elastycznego. Aby uzyskać więcej informacji, zobacz Azure.Provisioning.PostgreSql. Aby uzyskać więcej informacji, zobacz Azure. Dostosowywanie aprowizacji.

Nawiąż połączenie z istniejącym serwerem elastycznym AzurePostgreSQL

Być może masz istniejący serwer elastyczny AzurePostgreSQL, z którym chcesz nawiązać połączenie. Zamiast reprezentować nowy zasób serwera elastycznego AzurePostgreSQL, można dodać ciąg połączenia do hosta aplikacji. Aby dodać połączenie z istniejącym serwerem elastycznym AzurePostgreSQL, wywołaj metodę 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...

Notatka

Parametry połączenia służą do reprezentowania szerokiego zakresu informacji o połączeniu, w tym połączeń z bazą danych, brokerów komunikatów, identyfikatorów URI punktów końcowych i innych usług. W .NET.NET Aspire nomenklaturze termin "parametry połączenia" służy do reprezentowania wszelkich informacji o połączeniu.

Parametry połączenia są konfigurowane w konfiguracji hosta aplikacji, zazwyczaj w obszarze Wpisy tajne użytkownikaw sekcji ConnectionStrings. Host aplikacji wprowadza te parametry połączenia jako zmienną środowiskową do wszystkich zasobów zależnych, na przykład:

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

Zasób zależny może uzyskać dostęp do wstrzykiwanych parametrów połączenia, wywołując metodę GetConnectionString i przekazując nazwę połączenia jako parametr, w tym przypadku "postgres". Interfejs API GetConnectionString jest skrótem od IConfiguration.GetSection("ConnectionStrings")[name].

Uruchamianie zasobu AzurePostgreSQL jako kontenera

Integracja hostowania AzurePostgreSQL obsługuje uruchamianie serwera PostgreSQL jako kontenera lokalnego. Jest to korzystne w sytuacjach, w których chcesz uruchomić serwer PostgreSQL lokalnie na potrzeby programowania i testowania, unikając konieczności aprowizacji zasobu Azure lub nawiązywania połączenia z istniejącym serwerem AzurePostgreSQL.

Aby uruchomić serwer PostgreSQL jako kontener, wywołaj metodę 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);

Powyższy kod konfiguruje zasób AzurePostgreSQL Elastyczny Server do uruchamiania lokalnego w kontenerze.

Napiwek

Metoda RunAsContainer jest przydatna w przypadku lokalnego programowania i testowania. Interfejs API uwidacznia opcjonalny delegat, który umożliwia dostosowanie podstawowej konfiguracji PostgresServerResource, takich jak dodanie narzędzia pgAdmin, pgWeb, dodanie woluminu danych lub instalacji powiązania danych i dodanie instalacji powiązania init. Aby uzyskać więcej informacji, zobacz sekcję .NET AspirePostgreSQL integracji hostingu.

Konfigurowanie serwera AzurePostgreSQL do korzystania z uwierzytelniania haseł

Domyślnie serwer AzurePostgreSQL jest skonfigurowany do używania uwierzytelniania Microsoft Entra ID. Jeśli chcesz użyć uwierzytelniania za pomocą hasła, możesz skonfigurować serwer do korzystania z uwierzytelniania haseł, wywołując metodę 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);

Powyższy kod konfiguruje serwer AzurePostgreSQL do korzystania z uwierzytelniania haseł. Parametry username i password są dodawane do hosta aplikacji jako parametry, a metoda WithPasswordAuthentication jest wywoływana w celu skonfigurowania serwera AzurePostgreSQL do używania uwierzytelniania haseł. Aby uzyskać więcej informacji, zobacz Parametry zewnętrzne.

integracja Client

Aby rozpocząć pracę z integracją klienta .NET AspirePostgreSQL, zainstaluj pakiet NuGet 📦Aspire.Npgsql w projekcie wykorzystującym klienta, czyli w projekcie aplikacji korzystającej z klienta PostgreSQL. Integracja klienta PostgreSQL rejestruje instancję NpgsqlDataSource, którą można użyć do interakcji z PostgreSQL.

dotnet add package Aspire.Npgsql

Dodawanie klienta npgsql

W pliku Program.cs projektu wykorzystującego klienta wywołaj metodę rozszerzenia AddNpgsqlDataSource na dowolnym IHostApplicationBuilder, aby zarejestrować NpgsqlDataSource do użycia przy użyciu kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu serwera PostgreSQL w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Add PostgreSQL server resource.

Po dodaniu NpgsqlDataSource do konstruktora można pobrać wystąpienie NpgsqlDataSource przy użyciu wstrzykiwania zależności. Na przykład aby pobrać obiekt źródła danych z przykładowej usługi, zdefiniuj go jako parametr konstruktora i upewnij się, że klasa ExampleService jest zarejestrowana w kontenerze iniekcji zależności:

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

Aby uzyskać więcej informacji na temat wstrzykiwania zależności, zobacz .NET wstrzykiwanie zależności.

Dodaj zabezpieczony kluczem klient Npgsql

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień NpgsqlDataSource z różnymi nazwami połączeń. Aby zarejestrować kluczy klientów Npgsql, wywołaj metodę AddKeyedNpgsqlDataSource:

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

Następnie można uzyskać wystąpienia NpgsqlDataSource, korzystając z wstrzykiwania zależności. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług z kluczami, zobacz .NET wstrzykiwanie zależności: usługi z kluczami.

Konfiguracja

Integracja .NET AspirePostgreSQL zapewnia wiele metod konfiguracji i opcji spełniających wymagania i konwencje projektu.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings podczas wywoływania metody AddNpgsqlDataSource można podać nazwę parametrów połączenia:

builder.AddNpgsqlDataSource("postgresdb");

Następnie parametry połączenia zostaną pobrane z sekcji konfiguracji ConnectionStrings:

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

Aby uzyskać więcej informacji, zobacz ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspirePostgreSQL obsługuje Microsoft.Extensions.Configuration. Ładuje NpgsqlSettings z appsettings.json lub innych plików konfiguracji przy użyciu klucza Aspire:Npgsql. Przykład appsettings.json, który konfiguruje niektóre opcje:

W poniższym przykładzie przedstawiono plik appsettings.json, który konfiguruje niektóre z dostępnych opcji:

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

Aby uzyskać pełny schemat integracji klienta PostgreSQLJSON, zobacz Aspire. Npgsql/ConfigurationSchema.json.

Używaj delegatów wbudowanych

Możesz również przekazać delegata Action<NpgsqlSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje bezpośrednio, na przykład w celu wyłączenia sprawdzania stanu zdrowia.

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

Kontrole kondycji

Domyślnie integracje .NET.NET Aspire umożliwiają monitorowanie kondycji dla wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

  • Dodaje NpgSqlHealthCheck, który sprawdza, czy polecenia można pomyślnie wykonać względem bazowej bazy danych Postgres.
  • Integruje się z punktem końcowym HTTP /health, który wymaga, aby wszystkie zarejestrowane kontrole zdrowotności zostały pomyślnie zakończone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustanawiają konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji.

Rejestrowanie

Integracja .NET AspirePostgreSQL używa następujących kategorii dzienników:

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

Śledzenie

Integracja .NET AspirePostgreSQL spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • Npgsql

Metryki

Integracja .NET AspirePostgreSQL będzie emitować następujące metryki przy użyciu 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

Dodaj uwierzytelnionego klienta Npgsql Azure

Domyślnie, podczas wywoływania AddAzurePostgresFlexibleServer w integracji hostingu PostgreSQL, konfiguruje 📦AzureIdentity pakiet NuGet, aby włączyć uwierzytelnianie.

dotnet add package Azure.Identity

Połączenie PostgreSQL można używać przy użyciu integracji klienta i 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));
});

Powyższy fragment kodu pokazuje, jak używać klasy DefaultAzureCredential z pakietu Azure.Identity do uwierzytelniania za pomocą microsoft Entra ID i pobrać token do nawiązania połączenia z bazą danych PostgreSQL. Metoda UsePeriodicPasswordProvider służy do udostępniania tokenu konstruktorowi parametrów połączenia.

Zobacz też