intégration de .NET AspireOracleEntity Framework Core

Article
01/27/2025

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

Oracle Base de Données est un système de gestion de bases de données relationnelles très utilisé, développé et possédé par Oracle. L’intégration .NET AspireOracleEntity Framework Core vous permet de vous connecter à des serveurs Oracle existants ou de créer de nouveaux serveurs à partir de .NET avec l’image conteneur container-registry.orcale.com/databse/free.

Intégration de l’hébergement

L'hébergement .NET AspireOracle modélise le serveur comme type OracleDatabaseServerResource et la base de données comme type OracleDatabaseResource. Pour accéder à ces types et API, ajoutez le package NuGet 📦Aspire.Hosting.Oracle dans le projet hôte de l'application .

.NET CLI
packageReference

dotnet add package Aspire.Hosting.Oracle

<PackageReference Include="Aspire.Hosting.Oracle"
                  Version="*" />

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances des packages dans les applications .NET.

Ajouter des ressources de serveur et de base de données Oracle

Dans votre projet hôte d’application, appelez AddOracle pour ajouter et retourner un générateur de ressources de serveur Oracle. Chaînez un appel au générateur de ressources retourné pour AddDatabase, pour ajouter une base de données Oracle à la ressource serveur :

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracledb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb);
       .WaitFor(oracledb);

// After adding all resources, run the app...

Remarque

Le conteneur de base de données Oracle peut être lent à démarrer. Il est donc préférable d’utiliser une durée de vie persistante pour éviter les redémarrages inutiles. Pour plus d’informations, consultez durée de vie des ressources du conteneur.

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte d’application, comme illustré dans l’exemple précédent avec l’image container-registry.oracle.com/database/free, il crée un serveur Oracle sur votre ordinateur local. Une référence à votre générateur de ressources Oracle (la variable oracle) est utilisée pour ajouter une base de données. La base de données est nommée oracledb, puis ajoutée au ExampleProject. La ressource Oracle inclut une password aléatoire générée à l’aide de la méthode CreateDefaultPasswordParameter.

La méthode WithReference configure une connexion dans le ExampleProject nommé "oracledb". Pour plus d'informations, consultez Cycle de vie des ressources du conteneur.

Pourboire

Si vous préférez vous connecter à un serveur Oracle existant, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter Oracle ressource avec un paramètre de mot de passe

La ressource Oracle inclut les informations d’identification par défaut avec un mot de passe aléatoire. Oracle prend en charge les mots de passe par défaut basés sur la configuration à l’aide de la variable d’environnement ORACLE_PWD. Lorsque vous souhaitez fournir un mot de passe explicitement, vous pouvez le fournir en tant que paramètre :

var password = builder.AddParameter("password", secret: true);

var oracle = builder.AddOracle("oracle", password)
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracledb");

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(oracledb)
                       .WaitFor(oracledb);

Le code précédent obtient un paramètre à passer à l’API AddOracle et affecte en interne le paramètre à la variable d’environnement ORACLE_PWD du conteneur Oracle. Le paramètre password est généralement spécifié en tant que secret utilisateur :

{
  "Parameters": {
    "password": "Non-default-P@ssw0rd"
  }
}

Pour plus d’informations, consultez paramètres externes.

Ajouter une ressource Oracle avec le volume de données

Pour ajouter un volume de données à la ressource Oracle, appelez la méthode WithDataVolume :

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithDataVolume()
                    .WithLifetime(ContainerLifetime.Persistent);

var oracledb = oracle.AddDatabase("oracle");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb)
       .WaitFor(oracledb);

// After adding all resources, run the app...

Le volume de données est utilisé pour conserver les données Oracle en dehors du cycle de vie de son conteneur. Lorsqu’un paramètre name n’est pas fourni, le volume de données est monté à l'emplacement /opt/oracle/oradata dans le conteneur Oracle et le nom est généré aléatoirement. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés par rapport aux montages de liaison , consultez la documentation Docker : Volumes.

Avertissement

Le mot de passe est stocké dans le volume de données. Lors de l’utilisation d’un volume de données et si le mot de passe change, il ne fonctionnera pas tant que vous ne supprimez pas le volume.

Ajouter la ressource Oracle avec un montage de liaison de données

Pour ajouter un montage de liaison de données à la ressource Oracle, appelez la méthode WithDataBindMount :

var builder = DistributedApplication.CreateBuilder(args);

var oracle = builder.AddOracle("oracle")
                    .WithDataBindMount(source: @"C:\Oracle\Data");

var oracledb = oracle.AddDatabase("oracledb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(oracledb)
       .WaitFor(oracledb);

// After adding all resources, run the app...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes , qui offrent de meilleures performances, une portabilité accrue et une sécurité renforcée, les rendant ainsi plus adaptés aux environnements de production. Toutefois, les montages de liaison permettent un accès direct et une modification des fichiers sur le système hôte, ce qui est idéal pour le développement et les tests nécessitant des modifications en temps réel.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données Oracle entre les redémarrages de conteneur. Le montage de liaison de données est monté sur le chemin d’accès C:\Oracle\Data sur Windows (ou /Oracle/Data sur Unix) sur l’ordinateur hôte dans le conteneur Oracle. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.

Vérifications d’intégrité de l’intégration d’hébergement

L’intégration d’hébergement Oracle ajoute automatiquement un contrôle d’intégrité pour la ressource Oracle. La vérification d’intégrité vérifie que le serveur Oracle est en cours d’exécution et qu’une connexion peut être établie à celle-ci.

L’intégration de l'hébergement s'appuie sur le package AspNetCore.HealthChecks. NuGet 📦Oracle.

intégration de Client

Vous avez besoin d’une Oracle base de données et d’une chaîne de connexion pour accéder à la base de données. Pour commencer à utiliser l’intégration du client .NET AspireOracle, installez le 📦Aspire.Oracle. EntityFrameworkCore package NuGet dans le projet consommant le client, c’est-à-dire le projet pour l’application qui utilise le client Oracle. L’intégration du client Oracle inscrit une instance de DbContext que vous pouvez utiliser pour interagir avec Oracle.

.NET CLI
packageReference

dotnet add package Aspire.Oracle.EntityFrameworkCore

<PackageReference Include="Aspire.Oracle.EntityFrameworkCore"
                  Version="*" />

Ajouter Oracle client

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

builder.AddOracleDatabaseDbContext<ExampleDbContext>(connectionName: "oracledb");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource de base de données Oracle dans le projet hôte de l’application. En d’autres termes, lorsque vous appelez AddDatabase et fournissez un nom de oracledb ce même nom doit être utilisé lors de l’appel de AddOracleDatabaseDbContext. Pour plus d’informations, consultez Ajouter les ressources serveur et base de données Oracle.

Vous pouvez ensuite récupérer l’instance DbContext à 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(ExampleDbContext context)
{
    // Use database context...
}

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

Ajouter le contexte de la base de données Oracle avec enrichissement

Pour enrichir le DbContext avec des services supplémentaires, tels que les réessais automatiques, les contrôles de santé, la journalisation et la télémétrie, appelez la méthode EnrichOracleDatabaseDbContext :

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    connectionName: "oracledb",
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30 // seconds
    });

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

Paramétrage

L’intégration .NET AspireOracleEntity 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 builder.AddOracleDatabaseDbContext<TContext>():

builder.AddOracleDatabaseDbContext<ExampleDbContext>("oracleConnection");

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

{
  "ConnectionStrings": {
    "oracleConnection": "Data Source=TORCL;User Id=OracleUser;Password=Non-default-P@ssw0rd;"
  }
}

L'EnrichOracleDatabaseDbContext n’utilisera pas la section de configuration ConnectionStrings, car elle s’attend à ce qu’un DbContext soit inscrit au moment où il est appelé.

Pour plus d’informations, consultez la documentation ODP.NET.

Utiliser des fournisseurs de configuration

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

Voici un exemple de appsettings.json qui configure certaines des options disponibles :

{
  "Aspire": {
    "Oracle": {
      "EntityFrameworkCore": {
        "DisableHealthChecks": true,
        "DisableTracing": true,
        "DisableRetry": false,
        "CommandTimeout": 30
      }
    }
  }
}

Pourboire

La propriété CommandTimeout est en secondes. Lorsqu’il est défini comme indiqué dans l’exemple précédent, le délai d’expiration est de 30 secondes.

Utiliser des délégués en ligne

Vous pouvez également transmettre le délégué Action<OracleEntityFrameworkCoreSettings> pour configurer certaines ou toutes les options en ligne, par exemple pour désactiver les vérifications de santé à partir du code :

builder.AddOracleDatabaseDbContext<ExampleDbContext>(
    "oracle",
    static settings => settings.DisableHealthChecks  = true);

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    static settings => settings.DisableHealthChecks  = true);

Options de configuration

Voici les options configurables avec les valeurs par défaut correspondantes :

Nom	Description
`ConnectionString`	Chaîne de connexion de la base de données Oracle à laquelle se connecter.
`DisableHealthChecks`	Valeur booléenne qui indique si la vérification d’intégrité de la base de données est désactivée ou non.
`DisableTracing`	Valeur booléenne qui indique si le suivi OpenTelemetry est désactivé ou non.
`DisableRetry`	Valeur booléenne qui indique si les nouvelles tentatives de commande doivent être désactivées ou non.
`CommandTimeout`	Temps en secondes d’attente de l’exécution de la commande.

Vérifications d’intégrité

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

Par défaut, l’intégration .NET AspireOracleEntity Framework Core gère les éléments suivants :

Vérifie si le OracleEntityFrameworkCoreSettings.DisableHealthChecks est true.
Si c'est le cas, ajoute le DbContextHealthCheck, qui appelle la méthode CanConnectAsync de EF Core. Le nom de la vérification d’intégrité est le nom du type TContext.

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 AspireOracleEntity Framework Core utilise les catégories de journaux de logs suivantes :

Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Database.Connection
Microsoft.EntityFrameworkCore.Database.Transaction
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 AspireOracleEntity Framework Core émet les activités de suivi suivantes à l’aide de OpenTelemetry:

OpenTelemetry.Instrumentation.EntityFrameworkCore

Métriques

L’intégration .NET AspireOracleEntity Framework Core prend actuellement en charge les métriques suivantes :

Microsoft.EntityFrameworkCore

Partager via

intégration de .NET AspireOracleEntity Framework Core

Intégration de l’hébergement

Ajouter des ressources de serveur et de base de données Oracle

Ajouter Oracle ressource avec un paramètre de mot de passe

Ajouter une ressource Oracle avec le volume de données

Ajouter la ressource Oracle avec un montage de liaison de données

Vérifications d’intégrité de l’intégration d’hébergement

intégration de Client

Ajouter Oracle client

Ajouter le contexte de la base de données Oracle avec enrichissement

Paramétrage

Utiliser une chaîne de connexion

Utiliser des fournisseurs de configuration

Utiliser des délégués en ligne

Options de configuration

Vérifications d’intégrité

Observabilité et télémétrie

Exploitation forestière

Traçage

Métriques

Voir aussi

Ressources supplémentaires