Partilhar via

.NET Aspire Oracle Entity Framework Core integração

  • Artigo

Inclui:Integração de Hosting e IntegraçãoClient

Oracle Database é um sistema de gestão de base de dados relacional amplamente utilizado, propriedade e desenvolvido por Oracle. A integração .NET AspireOracleEntity Framework Core permite que você se conecte a servidores Oracle existentes ou crie novos servidores a partir de .NET com a imagem de contêiner container-registry.orcale.com/databse/free.

Integração de hospedagem

A integração de hospedagem .NET AspireOracle modela o servidor como o tipo OracleDatabaseServerResource e o banco de dados como o tipo OracleDatabaseResource. Para aceder a esses tipos e APIs, adicione o 📦Aspire.Hosting.Oracle pacote NuGet no projeto host da aplicação .

dotnet add package Aspire.Hosting.Oracle

Para obter mais informações, consulte dotnet add package ou Gerir dependências de pacotes em aplicações .NET.

Adicionar o servidor Oracle e recursos de banco de dados

No teu projeto de host de aplicação, invoca AddOracle para adicionar e retornar um construtor de recursos de servidor Oracle. Realize uma sequência de chamadas no builder de recursos retornado para AddDatabasepara adicionar um banco de dados Oracle ao recurso no servidor.

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

Observação

O contêiner de banco de dados Oracle pode ser lento para iniciar, por isso é melhor usar um tempo de vida persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Tempo de vida do recurso de contêiner.

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, como mostrado no exemplo anterior com a imagem container-registry.oracle.com/database/free, ele cria um novo servidor de Oracle em sua máquina local. Uma referência ao seu Oracle construtor de recursos (a variável oracle) é usada para adicionar um banco de dados. O banco de dados é nomeado oracledb e, em seguida, adicionado ao ExampleProject. O recurso Oracle inclui um password aleatório gerado usando o método CreateDefaultPasswordParameter.

O método WithReference configura uma conexão no ExampleProject chamado "oracledb". Para obter mais informações, consulte Ciclo de vida do recurso de contêiner.

Dica

Se você preferir se conectar a um servidor Oracle existente, ligue para AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a recursos existentes.

Adicionar recurso Oracle com o parâmetro palavra-passe

O recurso Oracle inclui credenciais padrão com uma senha aleatória. Oracle suporta senhas padrão baseadas em configuração usando a variável de ambiente ORACLE_PWD. Quando você deseja fornecer uma senha explicitamente, você pode fornecê-la como um parâmetro:

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

O código anterior obtém um parâmetro para passar para a API AddOracle e atribui internamente o parâmetro à variável de ambiente ORACLE_PWD do contêiner Oracle. O parâmetro password é geralmente especificado como um segredo de usuário :

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

Para obter mais informações, consulte Parâmetros externos.

Adicionar recurso Oracle com volume de dados

Para adicionar um volume de dados ao recurso Oracle, chame o método 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...

O volume de dados é usado para manter os dados Oracle fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /opt/oracle/oradata no contêiner Oracle e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados, e detalhes sobre por que eles são preferidos em relação a montagens bind , consulte a documentação Docker: Volumes.

Advertência

A senha é armazenada no volume de dados. Ao usar um volume de dados e se a senha for alterada, ela não funcionará até que você exclua o volume.

Adicionar recurso Oracle com montagem com associação de dados

Para adicionar uma montagem de ligação de dados ao recurso Oracle, chame o método 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...

Importante

Os suportes de ligação de de dados têm funcionalidade limitada em comparação com volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

As montagens de vinculação de dados dependem do sistema de arquivos da máquina host para persistir os dados Oracle durante as reinicializações do contêiner. A montagem de associação de dados é montada no caminho C:\Oracle\Data no Windows (ou /Oracle/Data no Unix) na máquina host no contêiner Oracle. Para obter mais informações sobre montagens de associação de dados, consulte Docker docs: Bind mounts.

Verificações de integridade da integração de hospedagem

A integração de hospedagem Oracle adiciona automaticamente uma verificação de integridade para o recurso Oracle. A verificação de integridade verifica se o servidor Oracle está em execução e se uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do 📦 AspNetCore.HealthChecks.Oracle pacote NuGet.

Client Integração

Você precisa de um banco de dados Oracle e uma cadeia de conexão para acessar o banco de dados. Para começar com a integração do cliente .NET AspireOracle, instale o pacote NuGet 📦Aspire.Oracle.EntityFrameworkCore no projeto consumidor, ou seja, o projeto para a aplicação que utiliza o cliente Oracle. A integração do cliente Oracle registra uma instância DbContext que você pode usar para interagir com Oracle.

dotnet add package Aspire.Oracle.EntityFrameworkCore

Adicionar Oracle cliente

No arquivo de Program.cs do seu projeto cliente-consumidor, chame o método de extensão AddOracleDatabaseDbContext em qualquer IHostApplicationBuilder para registar um DbContext para uso através do contentor de injeção de dependência. O método usa um parâmetro de nome de conexão.

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

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso de banco de dados Oracle no projeto host do aplicativo. Em outras palavras, quando você chama AddDatabase e fornece um nome de oracledb esse mesmo nome deve ser usado ao chamar AddOracleDatabaseDbContext. Para obter mais informações, consulte Adicionar recursos de servidor e banco de dados Oracle.

Em seguida, você pode recuperar a instância DbContext usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

public class ExampleService(ExampleDbContext context)
{
    // Use database context...
}

Para mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar contexto da base de dados Oracle com enriquecimento

Para enriquecer o DbContext com serviços adicionais, como repetições automáticas, verificações de integridade, registro em log e telemetria, chame o método EnrichOracleDatabaseDbContext:

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

O parâmetro settings é uma instância da classe OracleEntityFrameworkCoreSettings.

Configuração

A integração .NET AspireOracleEntity Framework Core fornece várias abordagens e opções de configuração para atender aos requisitos e convenções do seu projeto.

Usar uma cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração de ConnectionStrings, você fornece o nome da cadeia de conexão ao chamar builder.AddOracleDatabaseDbContext<TContext>():

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

A cadeia de conexão é recuperada da seção de configuração ConnectionStrings:

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

O EnrichOracleDatabaseDbContext não usará a seção de configuração ConnectionStrings, pois espera que um DbContext seja registrado no ponto em que é chamado.

Para obter mais informações, consulte a documentação do ODP.NET.

Usar provedores de configuração

A integração .NET AspireOracleEntity Framework Core suporta Microsoft.Extensions.Configuration de arquivos de configuração, como appsettings.json, usando a chave Aspire:Oracle:EntityFrameworkCore. Se você configurou suas configurações na seção Aspire:Oracle:EntityFrameworkCore, você pode simplesmente chamar o método sem passar nenhum parâmetro.

Segue-se um exemplo de um appsettings.json que configura algumas das opções disponíveis:

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

Dica

A propriedade CommandTimeout é medida em segundos. Quando definido como mostrado no exemplo anterior, o tempo limite é de 30 segundos.

Usar delegados embutidos

Você também pode passar o delegado Action<OracleEntityFrameworkCoreSettings> para configurar algumas ou todas as opções em linha, por exemplo, para desativar as verificações de integridade a partir do código:

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

ou

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

Opções de configuração

Aqui estão as opções configuráveis com os valores padrão correspondentes:

Nome Descrição
ConnectionString A cadeia de conexão do banco de dados Oracle ao qual se conectar.
DisableHealthChecks Um valor booleano que indica se a verificação de integridade do banco de dados está desabilitada ou não.
DisableTracing Um valor booleano que indica se o rastreamento de OpenTelemetry está desabilitado ou não.
DisableRetry Um valor booleano que indica se as novas tentativas de comando devem ser desabilitadas ou não.
CommandTimeout O tempo em segundos para aguardar a execução do comando.

Controlos sanitários

Por padrão, as integrações .NET.NET Aspire habilitam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral das integrações.

Por padrão, a integração de .NET AspireOracleEntity Framework Core lida com o seguinte:

Observabilidade e telemetria

.NET .NET Aspire integrações automaticamente configuram Registo, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na seção Configuração.

Registo

A integração .NET AspireOracleEntity Framework Core usa as seguintes categorias de log:

  • 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

Rastreio

A integração .NET AspireOracleEntity Framework Core emitirá as seguintes atividades de rastreio utilizando OpenTelemetry:

  • OpenTelemetry. Instrumentação.EntityFrameworkCore

Métricas

Atualmente, a integração .NET AspireOracleEntity Framework Core suporta as seguintes métricas:

  • Microsoft.EntityFrameworkCore

Ver também