Partager via

intégration de .NET AspireAzurePostgreSQLEntity Framework Core

  • Article

inclut : l’intégration d’hébergement et l’intégration de Client

Azure Database pour PostgreSQL— Flexible Server 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 .NET AspireAzurePostgreSQL modélisent 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 comme ressources dans votre projet hôte d’application , installez le 📦Aspire.Hosting.Azure.PostgreSQL paquet NuGet :

dotnet add package Aspire.Hosting.Azure.PostgreSQL

Pour plus d’informations, consultez dotnet add package.

L’intégration de l’hébergement AzurePostgreSQL dépend du package NuGet 📦Aspire.Hosting.PostgreSQL, l’étendant pour supporter 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, consultez intégration.

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 provisionnement Bicep

Si vous êtes nouveau dans le domaine de Bicep, sachez qu'il s'agit d'un langage spécifique au domaine pour définir les ressources Azure. Avec .NET.NET Aspire, vous n’avez pas besoin d’écrire Bicep en main, car les API d’approvisionnement génèrent Bicep pour vous. Lorsque vous publiez votre application, le fichier Bicep généré est livré en même temps que le fichier manifeste. Lorsque vous ajoutez une ressource AzurePostgreSQL, le Bicep suivant est généré :

@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 de personnaliser le Bicep généré en offrant 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 de serveur PostgreSQL :

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 et 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 Azure flexible PostgreSQLServer 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 PostgresServerResource sous-jacente. Par exemple, vous pouvez ajouter pgAdmin et pgWeb, ajouter un volume de données ou un montage de liaison de données, et ajouter un montage de liaison d'initialisation. 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 AspirePostgreSQLEntity Framework Core, installez le package NuGet 📦Aspire.Npgsql.EntityFrameworkCore.PostgreSQL dans le projet de l'application qui utilise le client PostgreSQL, c'est-à-dire le projet qui consomme le client. L’intégration du client .NET AspirePostgreSQLEntity Framework Core inscrit vos instances de sous-classe DbContext souhaitées que vous pouvez utiliser pour interagir avec PostgreSQL.

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL

Ajouter un contexte de base de données Npgsql

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

builder.AddNpgsqlDbContext<YourDbContext>(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 la ressource serveur PostgreSQL.

Après avoir ajouté YourDbContext au générateur, vous pouvez obtenir l’instance YourDbContext à 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(YourDbContext context)
{
    // Use context...
}

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

Enrichir un contexte de base de données Npgsql

Vous préférez peut-être utiliser la méthode Entity Framework standard pour obtenir un contexte de base de données et l’ajouter au conteneur d’injection de dépendances :

builder.Services.AddDbContext<YourDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("postgresdb")
        ?? throw new InvalidOperationException("Connection string 'postgresdb' not found.")));

Note

Le nom de la chaîne de connexion que vous passez à la méthode GetConnectionString 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 la ressource serveur PostgreSQL.

Vous disposez d’une plus grande flexibilité lorsque vous créez le contexte de base de données de cette façon, par exemple :

  • Vous pouvez réutiliser le code de configuration existant pour le contexte de base de données sans le réécrire pour .NET.NET Aspire.
  • Vous pouvez utiliser les intercepteurs Entity Framework Core pour modifier les opérations de base de données.
  • Vous pouvez choisir de ne pas utiliser le regroupement de contextes Entity Framework Core, ce qui peut mieux fonctionner dans certaines circonstances.

Si vous utilisez cette méthode, vous pouvez améliorer le contexte de la base de données avec des réessais de style .NET.NET Aspire, des contrôles de l'intégrité, la journalisation, et des fonctionnalités de télémétrie en appelant la méthode EnrichNpgsqlDbContext :

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

Le paramètre settings est une instance de la classe NpgsqlEntityFrameworkCorePostgreSQLSettings.

Configuration

L’intégration .NET AspirePostgreSQLEntity Framework Core 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 fournissez le nom de la chaîne de connexion lors de l’appel de la méthode AddNpgsqlDbContext :

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

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

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

La EnrichNpgsqlDbContext n’utilise pas la section de configuration ConnectionStrings, car elle s’attend à ce qu’un DbContext soit inscrit au point où il est appelé.

Pour plus d’informations, consultez le ConnectionString.

Utiliser des fournisseurs de configuration

L’intégration .NET AspirePostgreSQLEntity Framework Core prend en charge Microsoft.Extensions.Configuration. Il charge le NpgsqlEntityFrameworkCorePostgreSQLSettings à partir de fichiers de configuration tels que appsettings.json à l’aide de la clé Aspire:Npgsql:EntityFrameworkCore:PostgreSQL. Si vous avez configuré vos configurations dans la section Aspire:Npgsql:EntityFrameworkCore:PostgreSQL, vous pouvez simplement appeler la méthode sans passer de paramètre.

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

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

Pour obtenir le schéma complet d’intégration PostgreSQLEntity Framework Core client JSON, consultez Aspire. Npgsql.EntityFrameworkCore.PostgreSQL/ConfigurationSchema.json.

Utiliser des délégués en ligne

Vous pouvez également utiliser le délégué Action<NpgsqlEntityFrameworkCorePostgreSQLSettings> pour configurer certaines ou toutes les options directement, par exemple pour définir le ConnectionString :

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

Configurer plusieurs classes DbContext

Si vous souhaitez inscrire plusieurs DbContext avec une configuration différente, vous pouvez utiliser $"Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:{typeof(TContext).Name}" nom de section de configuration. La configuration json se présente comme suit :

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

Ensuite, l’appel de la méthode AddNpgsqlDbContext avec le paramètre de type AnotherDbContext charge les paramètres à partir de la section Aspire:Npgsql:EntityFrameworkCore:PostgreSQL:AnotherDbContext.

builder.AddNpgsqlDbContext<AnotherDbContext>();

Client contrôles de santé de l’intégration

Par défaut, les intégrations de clients .NET.NET Aspire ont les contrôles de santé activés pour tous les services. De même, de nombreuses intégrations d'hébergement .NET.NET Aspire activent également les endpoints de vérification de santé. Pour plus d’informations, consultez :

Par défaut, les intégrations .NET AspirePostgreSQLEntity Framework Core gèrent les éléments suivants :

  • Ajoute la DbContextHealthCheck, qui appelle la méthode CanConnectAsync de EF Core. Le nom de la vérification de santé est le nom du type TContext.
  • S’intègre au point de terminaison HTTP /health, qui spécifie que toutes les vérifications d’intégrité enregistrées doivent être réussies pour que l’application soit prête à accepter le flux de données.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées 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 AspirePostgreSQLEntity Framework Core utilise les catégories de logs suivantes :

  • 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

Traçage

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

  • Npgsql

Mesures

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

Ajouter Azure client Npgsql authentifié

Par défaut, lorsque vous appelez AddAzurePostgresFlexibleServer dans votre intégration d’hébergement PostgreSQL, il nécessite 📦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.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));
});

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