Udostępnij za pośrednictwem

integracja .NET AspireAzurePostgreSQL

Obejmuje:integracja hostingu obejmuje integrację hostingu — Client integracja dołączonaClient

Azure Database for PostgreSQL—Elastyczny Server to usługa relacyjnej bazy danych oparta na silniku bazy danych typu open source 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 pozwala łączyć się z istniejącymi AzurePostgreSQL bazami danych lub tworzyć nowe wystąpienia na podstawie .NETobrazu konteneradocker.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 do wyrażania ich jako zasobów w projekcie hosta aplikacji, zainstaluj pakiet NuGet 📦Aspire.Hosting.Azure.PostgreSQL:

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Aby uzyskać więcej informacji, zobacz dotnet add package.

Integracja hostingu AzurePostgreSQL jest zależna od pakietu NuGet 📦Aspire.Hosting.PostgreSQL, rozszerzając go w celu obsługi Azure. Wszystko, co możesz zrobić z integracją .NET AspirePostgreSQL i integracją .NET AspirePostgreSQLEntity Framework Core, możesz 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 PostgresSQL do wdrożenia jako AzurePostgres Elastyczny Server.

Ważny

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

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 Local provisioning: Configuration (Aprowizowanie lokalne: konfiguracja).

Bicep wygenerowany przez prowizjonowanie

Jeśli dopiero zaczynasz korzystać z aplikacji Bicep, jest to język specyficzny dla domeny do definiowania Azure zasobów. W przypadku .NET.NET Aspirenie musisz ręcznie pisać aplikacji Bicep, ponieważ interfejsy API aprowizacji generują dla Ciebie kod Bicep. Podczas publikowania aplikacji, wygenerowany plik Bicep zostaje wyeksportowany razem z plikiem manifestu. Po dodaniu zasobu AzurePostgreSQL zostanie wygenerowany następujący 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

Poprzedni Bicep to moduł, który dostarcza elastyczny zasób serwera AzurePostgreSQL. Ponadto w osobnym module tworzone są przypisania ról dla zasobu Azure.

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

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 ma wpływ na zmiany w infrastrukturze aprowizacji w języku C#. Modyfikacje pliku Bicep, które zostaną wprowadzone bezpośrednio, będą nadpisane. Dlatego należy wprowadzać je za pośrednictwem interfejsów API aprowizowania w języku C#, aby zapewnić, że zostaną odzwierciedlone w wygenerowanych plikach.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego elementu Bicep, oferując płynny interfejs API do konfiguracji zasobów Azure za pomocą 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 serwera PostgreSQL:

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

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 i Azure. Dostosowywanie konfiguracji.

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. Połącz wywołanie z adnotacją, że AzurePostgresFlexibleServerResource jest to istniejący zasób:

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

Aby uzyskać więcej informacji na temat traktowania AzurePostgreSQL elastycznych zasobów serwera jako istniejących zasobów, zobacz Korzystanie z istniejących Azure zasobów.

Uwaga

Alternatywnie, zamiast reprezentować zasób elastycznego serwera AzurePostgreSQL, można dodać ciąg połączenia do hosta aplikacji. Takie podejście jest słabo typizowane i nie działa z przypisaniami ról ani dostosowaniami infrastruktury. Aby uzyskać więcej informacji, zobacz Dodaj istniejące zasoby Azure z parametrami połączenia.

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. API udostępnia opcjonalnego delegata, który umożliwia dostosowanie podstawowej konfiguracji PostgresServerResource. Na przykład możesz dodać narzędzie pgAdmin i pgWeb, dodać wolumin danych lub powiązanie danych, oraz dodać powiązanie init. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą integracji hostingu.NET AspirePostgreSQL.

Konfigurowanie serwera AzurePostgreSQL do korzystania z uwierzytelniania haseł

Domyślnie AzurePostgreSQL serwer jest skonfigurowany do używania uwierzytelniania identyfikatora Entra firmy Microsoft . 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ą .NET AspireAzurePostgreSQL klienta, zainstaluj pakiet NuGet 📦Aspire.Azure.Npgsql w projekcie aplikacji korzystającej z PostgreSQL klienta. Integracja PostgreSQL klienta rejestruje wystąpienie NpgsqlDataSource, którego można użyć do interakcji z PostgreSQL.

dotnet add package Aspire.Azure.Npgsql

Połączenie PostgreSQL można wykorzystać przy użyciu integracji klienta, wywołując AddAzureNpgsqlDataSource.

builder.AddAzureNpgsqlDataSource(connectionName: "postgresdb");

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu serwera PostgreSQL w projekcie hosta aplikacji.

W poprzednim fragmencie kodu pokazano, jak za pomocą metody AddAzureNpgsqlDataSource zarejestrować wystąpienie NpgsqlDataSource, które korzysta z uwierzytelniania Azure (Microsoft Entra ID). Ta "postgresdb" nazwa połączenia odpowiada wartości konfiguracji parametrów połączenia.

Po dodaniu NpgsqlDataSource do buildera, można uzyskać instancję NpgsqlDataSource za pomocą 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 klucz Azure klienta Npgsql

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

builder.AddKeyedAzureNpgsqlDataSource(name: "sales_db");
builder.AddKeyedAzureNpgsqlDataSource(name: "inventory_db");

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("sales_db")] NpgsqlDataSource salesDataSource,
    [FromKeyedServices("inventory_db")] NpgsqlDataSource inventoryDataSource)
{
    // Use data sources...
}

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

Konfiguracja

Integracja serwera .NET AspireAzure Npgsql oferuje wiele opcji konfigurowania połączenia bazy danych na podstawie wymagań i konwencji projektu.

Użyj łańcucha połączenia

W przypadku używania parametrów połączenia zdefiniowanych w ConnectionStrings sekcji konfiguracji należy podać nazwę parametrów połączenia podczas wywoływania polecenia AddAzureNpgsqlDataSource:

builder.AddAzureNpgsqlDataSource("postgresdb");

Parametry połączenia są pobierane z ConnectionStrings sekcji konfiguracji, na przykład należy wziąć pod uwagę następującą JSON konfigurację:

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

Aby uzyskać więcej informacji na temat konfigurowania parametrów połączenia, zobacz dokumentację parametrów połączenia npgsql.

Uwaga

Nazwa użytkownika i hasło są automatycznie wnioskowane z poświadczeń podanych w ustawieniach.

Korzystanie z dostawców konfiguracji

Integracja z .NET AspireAzure serwerem Npgsql obsługuje funkcję Microsoft.Extensions.Configuration. Ładuje element AzureNpgsqlSettings z konfiguracji przy użyciu klucza Aspire:Azure:Npgsql. Rozważmy na przykład następujący plik appsettings.json , który konfiguruje niektóre z dostępnych opcji:

{
  "Aspire": {
    "Npgsql": {
      "DisableHealthChecks": true,
      "DisableTracing": true
    }
  }
}
Używaj delegatów wewnętrznych

Ustawienia w kodzie można skonfigurować, przekazując delegata Action<AzureNpgsqlSettings> configureSettings w celu skonfigurowania niektórych lub wszystkich wbudowanych opcji, na przykład w celu wyłączenia kontroli kondycji z kodu:

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

Użyj właściwości AzureNpgsqlSettings.Credential, aby nawiązać połączenie. Jeśli żadne poświadczenie nie jest skonfigurowane, użyte zostanie DefaultAzureCredential. Gdy parametry połączenia zawierają nazwę użytkownika i hasło, poświadczenie jest ignorowane.

Client kontrole stanu integracji

Domyślnie .NET.NET Aspireintegracje klientów mają włączone kontrole kondycji dla wszystkich usług. Podobnie wiele .NET.NET Aspireintegracji hostingu umożliwia również punkty końcowe sprawdzania kondycji. Aby uzyskać więcej informacji, zobacz:

  • Dodaje NpgSqlHealthCheck, który sprawdza, czy polecenia można pomyślnie wykonać wobec podstawowej 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 konfigurują konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwacji. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz .NET.NET Aspire Omówienie integracji. 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 .

Logowanie

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 generowanie 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

Zobacz też