Partager via

intégration de .NET AspireAzurePostgreSQL

  • Article

inclut :intégration d'hébergement et intégrationClient

Azure Database pour PostgreSQL: Server flexible est un service de base de données relationnelle basé sur le moteur de base de données open source Postgres. Il s’agit d’une base de données entièrement managée en tant que service qui peut gérer des charges de travail stratégiques avec des performances prévisibles, la sécurité, la haute disponibilité et l’extensibilité dynamique. L’intégration .NET AspireAzurePostgreSQL permet de se connecter à des bases de données AzurePostgreSQL existantes ou de créer de nouvelles instances à partir de .NET avec l’image conteneur docker.io/library/postgres.

Intégration de l’hébergement

Les modèles d'intégration d'hébergement de .NET AspireAzurePostgreSQL modèlent un serveur et une base de données flexibles PostgreSQL en tant que types AzurePostgresFlexibleServerResource et AzurePostgresFlexibleServerDatabaseResource. D’autres types qui sont intrinsèquement disponibles dans l’intégration d’hébergement sont représentés dans les ressources suivantes :

Pour accéder à ces types et API pour les exprimer en tant que ressources dans votre projet hôte d’application , installez le paquet NuGet 📦Aspire.Hosting.Azure.PostgreSQL :

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Pour plus d’informations, consultez dotnet add package.

L'intégration de l'hébergement AzurePostgreSQL repose sur le package NuGet 📦Aspire.Hosting.PostgreSQL, l'étendant pour prendre en charge Azure. Tout ce que vous pouvez faire avec l’intégration .NET AspirePostgreSQL et l’intégration .NET AspirePostgreSQLEntity Framework Core, vous pouvez également le faire avec cette intégration.

Ajouter une ressource de serveur AzurePostgreSQL

Une fois que vous avez installé l’intégration d’hébergement .NET AspireAzurePostgreSQL, appelez la méthode d’extension AddAzurePostgresFlexibleServer dans votre projet hôte d’application :

var builder = DistributedApplication.CreateBuilder(args);

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

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

L’appel précédent à AddAzurePostgresFlexibleServer configure la ressource de serveur PostgresSQL à déployer en tant que AzurePostgres flexible Server.

Important

Par défaut, AddAzurePostgresFlexibleServer configure l’authentification Microsoft Entra ID. Cela nécessite des modifications apportées aux applications qui doivent se connecter à ces ressources. Pour plus d’informations, voir l’intégration deClient .

Pourboire

Lorsque vous appelez AddAzurePostgresFlexibleServer, il appelle implicitement AddAzureProvisioning, ce qui ajoute la prise en charge de la génération dynamique de ressources Azure pendant le démarrage de l’application. L’application doit configurer l’abonnement et l’emplacement appropriés. Pour plus d’informations, consultez Provisionnement local : Configuration.

Génération de scripts Bicep pour l'approvisionnement

Si vous débutez avec Bicep, c'est un langage de domaine spécifique pour définir les ressources Azure. Avec .NET.NET Aspire, vous n’avez pas besoin d’écrire Bicep manuellement, au lieu de cela, les API d’approvisionnement génèrent Bicep pour vous. Lorsque vous publiez votre application, le fichier Bicep généré est joint en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource AzurePostgreSQL, le Bicep suivant est généré :


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

Bicep précédent est un module qui provisionne un serveur flexible AzurePostgreSQL avec les valeurs par défaut suivantes :

  • authConfig: configuration d’authentification du serveur PostgreSQL. La valeur par défaut est ActiveDirectoryAuth activée et PasswordAuth désactivée.
  • availabilityZone: zone de disponibilité du serveur PostgreSQL. La valeur par défaut est 1.
  • backup: configuration de sauvegarde du serveur PostgreSQL. La valeur par défaut est BackupRetentionDays définie sur 7 et GeoRedundantBackup définie sur Disabled.
  • highAvailability: configuration de haute disponibilité du serveur PostgreSQL. La valeur par défaut est Disabled.
  • storage: configuration de stockage du serveur PostgreSQL. La valeur par défaut est StorageSizeGB définie sur 32.
  • version: version du serveur PostgreSQL. La valeur par défaut est 16.
  • sku: référence SKU du serveur PostgreSQL. La valeur par défaut est Standard_B1ms.
  • tags: balises du serveur PostgreSQL. La valeur par défaut est aspire-resource-name définie sur le nom de la ressource Aspire, dans ce cas postgres-flexible.

Outre le serveur flexible PostgreSQL, il provisionne également une règle de pare-feu Azure pour autoriser toutes les adresses IP Azure. Enfin, un administrateur est créé pour le serveur PostgreSQL et la chaîne de connexion est générée en tant que variable de sortie. Bicep généré est un point de départ et peut être personnalisé pour répondre à vos besoins spécifiques.

Personnaliser l’infrastructure d’approvisionnement

Toutes les ressources .NET AspireAzure sont des sous-classes du type AzureProvisioningResource. Ce type permet la personnalisation du code Bicep généré en fournissant une API fluide pour configurer les ressources Azure à l’aide de l’API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Par exemple, vous pouvez configurer le kind, consistencyPolicy, locations, etc. L’exemple suivant montre comment personnaliser la ressource 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");
    });

Code précédent :

Il existe de nombreuses options de configuration supplémentaires pour personnaliser la ressource de serveur flexible PostgreSQL. Pour plus d’informations, consultez Azure.Provisioning.PostgreSql. Pour plus d’informations, consultez Azure. Personnalisation de l’approvisionnement.

Se connecter à un serveur flexible AzurePostgreSQL existant

Vous disposez peut-être d’un serveur flexible AzurePostgreSQL existant auquel vous souhaitez vous connecter. Au lieu de représenter une nouvelle ressource de serveur flexible AzurePostgreSQL, vous pouvez ajouter une chaîne de connexion à l’hôte de l’application. Pour ajouter une connexion à un serveur flexible AzurePostgreSQL existant, appelez la méthode 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...

Note

Les chaînes de connexion sont utilisées pour représenter un large éventail d’informations de connexion, notamment les connexions de base de données, les répartiteurs de messages, les URI de point de terminaison et d’autres services. Dans .NET.NET Aspire nomenclature, le terme « chaîne de connexion » est utilisé pour représenter n’importe quel type d’informations de connexion.

La chaîne de connexion est configurée dans la configuration de l’hôte d’application, généralement sous secrets utilisateur, sous la section ConnectionStrings. L’hôte de l’application injecte cette chaîne de connexion en tant que variable d’environnement dans toutes les ressources dépendantes, par exemple :

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

La ressource dépendante peut accéder à la chaîne de connexion injectée en appelant la méthode GetConnectionString et en passant le nom de connexion en tant que paramètre, dans ce cas "postgres". L’API GetConnectionString est abrégée pour IConfiguration.GetSection("ConnectionStrings")[name].

Exécuter AzurePostgreSQL ressource en tant que conteneur

L’intégration d’hébergement AzurePostgreSQL prend en charge l’exécution du serveur PostgreSQL en tant que conteneur local. Cela est avantageux pour les situations où vous souhaitez exécuter le serveur PostgreSQL localement à des fins de développement et de test, en évitant la nécessité de provisionner une ressource Azure ou de vous connecter à un serveur AzurePostgreSQL existant.

Pour exécuter le serveur PostgreSQL en tant que conteneur, appelez la méthode 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);

Le code précédent configure une ressource de Server flexible AzurePostgreSQL pour s’exécuter localement dans un conteneur.

Pourboire

La méthode RunAsContainer est utile pour le développement et les tests locaux. L’API expose un délégué facultatif qui vous permet de personnaliser la configuration de PostgresServerResource sous-jacente, par exemple l’ajout de pgAdmin, pgWeb, l’ajout d’un volume de données ou d’un montage de liaison de données et l’ajout d’un montage de liaison init. Pour plus d’informations, consultez la section d’intégration d’hébergement .NET AspirePostgreSQL.

Configurer le serveur AzurePostgreSQL pour utiliser l’authentification par mot de passe

Par défaut, le serveur AzurePostgreSQL est configuré pour utiliser 'authentification microsoft Entra ID. Si vous souhaitez utiliser l’authentification par mot de passe, vous pouvez configurer le serveur pour utiliser l’authentification par mot de passe en appelant la méthode 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);

Le code précédent configure le serveur AzurePostgreSQL pour utiliser l’authentification par mot de passe. Les paramètres username et password sont ajoutés à l’hôte de l’application en tant que paramètres, et la méthode WithPasswordAuthentication est appelée pour configurer le serveur AzurePostgreSQL pour utiliser l’authentification par mot de passe. Pour plus d’informations, consultez paramètres externes.

intégration de Client

Pour commencer à utiliser l’intégration du client .NET AspirePostgreSQL, installez le package NuGet 📦Aspire.Npgsql dans le projet consommateur, autrement dit, le projet de l’application qui utilise le client PostgreSQL. L’intégration du client PostgreSQL inscrit une instance NpgsqlDataSource que vous pouvez utiliser pour interagir avec PostgreSQL.

dotnet add package Aspire.Npgsql

Ajouter un client Npgsql

Dans le fichier Program.cs de votre projet consommant le client, appelez la méthode d’extension AddNpgsqlDataSource sur n’importe quelle IHostApplicationBuilder pour inscrire un NpgsqlDataSource à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource de serveur PostgreSQL dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter PostgreSQL ressource de serveur.

Après avoir ajouté NpgsqlDataSource au générateur, vous pouvez obtenir l’instance NpgsqlDataSource à l’aide de l’injection de dépendances. Par exemple, pour récupérer votre objet source de données à partir d’un exemple de service, définissez-le en tant que paramètre de constructeur et vérifiez que la classe ExampleService est inscrite auprès du conteneur d’injection de dépendances :

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

Pour plus d'informations sur l'injection de dépendances, consultez .NET injection de dépendances.

Ajouter un client Npgsql avec identifiant

Il peut arriver que vous souhaitiez inscrire plusieurs instances de NpgsqlDataSource avec différents noms de connexion. Pour inscrire des clients Npgsql à clé, utilisez la méthode AddKeyedNpgsqlDataSource :

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

Vous pouvez ensuite récupérer les instances NpgsqlDataSource à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

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

Pour plus d’informations sur les services à clé, consultez .NET injection de dépendances : services à clé.

Configuration

L’intégration .NET AspirePostgreSQL fournit plusieurs approches et options de configuration pour répondre aux exigences et conventions de votre projet.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, vous pouvez fournir le nom de la chaîne de connexion lors de l’appel de la méthode AddNpgsqlDataSource :

builder.AddNpgsqlDataSource("postgresdb");

Ensuite, la chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

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

Pour plus d’informations, consultez la chaîne de connexion.

Utiliser des fournisseurs de configuration

L’intégration .NET AspirePostgreSQL prend en charge Microsoft.Extensions.Configuration. Il charge le NpgsqlSettings à partir de appsettings.json ou d’autres fichiers de configuration à l’aide de la clé Aspire:Npgsql. Exemple appsettings.json qui configure certaines des options suivantes :

L’exemple suivant montre un fichier appsettings.json qui configure certaines des options disponibles :

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

Pour obtenir le schéma complet de l’intégration du client PostgreSQLJSON, consultez Aspire. Npgsql/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<NpgsqlSettings> configureSettings pour configurer certaines ou toutes les options directement, par exemple pour désactiver les vérifications d’intégrité :

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

Vérifications d’intégrité

Par défaut, .NET.NET Aspire intégrations permettent contrôles de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

  • Ajoute le NpgSqlHealthCheck, qui vérifie que les commandes peuvent être exécutées avec succès sur la base de données Postgres sous-jacente.
  • S’intègre au point de terminaison HTTP /health, qui spécifie que tous les contrôles de santé inscrits doivent être réussis pour que l’application soit considérée prête à recevoir du trafic.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement la journalisation, le suivi et les métriques, parfois appelés les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration .NET AspirePostgreSQL utilise les catégories de journaux suivantes :

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

Traçage

L’intégration .NET AspirePostgreSQL émet les activités de suivi suivantes à l’aide de OpenTelemetry:

  • Npgsql

Métriques

L’intégration .NET AspirePostgreSQL émet les métriques suivantes à l’aide de 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

Ajouter Azure client Npgsql authentifié

Par défaut, lorsque vous appelez AddAzurePostgresFlexibleServer dans votre intégration d’hébergement PostgreSQL, il configure 📦Azure. Identity package NuGet pour activer l’authentification :

dotnet add package Azure.Identity

La connexion PostgreSQL peut être consommée à l’aide de l’intégration du client et 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));
});

L’extrait de code précédent montre comment utiliser la classe DefaultAzureCredential à partir du package Azure.Identity pour s’authentifier auprès de Microsoft Entra ID et récupérer un jeton pour se connecter à la base de données PostgreSQL. La méthode UsePeriodicPasswordProvider est utilisée pour fournir le jeton au générateur de chaînes de connexion.

Voir aussi