Compartilhar via

integração .NET AspireOracleEntity Framework Core

  • Artigo

Inclui: de integração de hospedagem e Client de integração

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

Integração de hospedagem

O .NET AspireOracle de integração de hospedagem modela o servidor como o tipo de OracleDatabaseServerResource e o banco de dados como o tipo de OracleDatabaseResource. Para acessar esses tipos e APIs, adicione o 📦Aspire.Hosting.Oracle pacote NuGet no projeto do host do aplicativo .

dotnet add package Aspire.Hosting.Oracle

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

Adicionar servidor Oracle e recursos de banco de dados

No projeto de host do aplicativo, chame AddOracle para adicionar e retornar um construtor de recursos do servidor Oracle. Encadear uma chamada ao construtor de recursos retornado para AddDatabase, para adicionar um banco de dados Oracle ao recurso do 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...

Nota

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

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem container-registry.oracle.com/database/free, ele cria um novo servidor Oracle em seu computador local. Uma referência ao construtor de recursos Oracle (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 denominado "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, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar recurso Oracle com o parâmetro de senha

O recurso Oracle inclui credenciais padrão com uma senha aleatória. Oracle dá suporte a 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 a ser passado 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 do 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 persistir os dados de 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 preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.

Aviso

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 o recurso Oracle com montagem de vínculo de dados

Para adicionar uma montagem de vinculaçã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 de dados associam montagens 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 de vinculação permitem acesso direto e modificação dos arquivos no sistema host, sendo ideal para desenvolvimento e teste, onde mudanças em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos do computador host para persistir os dados Oracle entre reinicializações de contêiner. A montagem de vinculação de dados é efetuada no caminho C:\Oracle\Data no Windows (ou /Oracle/Data no Unix) no computador host dentro do contêiner Oracle. Para obter mais informações sobre montagens de vínculo de dados, consulte a documentação Docker: Montagens de vínculo.

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

A integração de hospedagem Oracle adiciona automaticamente uma verificação de integridade para o recurso de 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 pacote NuGet 📦 AspNetCore.HealthChecks.Oracle.

integração Client

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

dotnet add package Aspire.Oracle.EntityFrameworkCore

Adicionar Oracle cliente

No arquivo Program.cs do projeto que consome o cliente, chame o método de extensão AddOracleDatabaseDbContext em qualquer IHostApplicationBuilder para registrar um DbContext para uso por meio do contêiner 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 de 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 Oracle servidor e recursos de banco de dados.

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

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

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

Enriquecer o contexto do banco de dados Oracle

Você pode preferir usar o método Entity Framework padrão para obter um contexto de banco de dados e adicioná-lo ao contêiner de injeção de dependência:

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseOracle(builder.Configuration.GetConnectionString("oracledb")
        ?? throw new InvalidOperationException("Connection string 'oracledb' not found.")));

Nota

O nome da cadeia de conexão que você passa para o método GetConnectionString deve corresponder ao nome usado ao adicionar o recurso Oracle no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar Oracle servidor e recursos de banco de dados.

Você tem mais flexibilidade ao criar o contexto do banco de dados dessa maneira, por exemplo:

  • Você pode reutilizar o código de configuração existente para o contexto do banco de dados sem reescrevê-lo para .NET.NET Aspire.
  • Você pode usar Entity Framework Core interceptores para modificar operações de banco de dados.
  • Você pode optar por não usar a agregação de contexto Entity Framework Core, o que pode ter um desempenho melhor em algumas circunstâncias.

Se você usar esse método, poderá aprimorar o contexto do banco de dados com repetições de estilo .NET.NET Aspire, verificações de integridade, registro em log e recursos de telemetria chamando o método EnrichOracleDatabaseDbContext:

builder.EnrichOracleDatabaseDbContext<ExampleDbContext>(
    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 de configuração e opções 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 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 do 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 de ConnectionStrings, pois espera que um DbContext seja registrado no ponto em que é chamado.

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

Usar provedores de configuração

A integração .NET AspireOracleEntity Framework Core oferece suporte a Microsoft.Extensions.Configuration com arquivos de configuração, como appsettings.json, ao usar a chave Aspire:Oracle:EntityFrameworkCore. Se você tiver configurado suas configurações na seção Aspire:Oracle:EntityFrameworkCore, poderá simplesmente chamar o método sem passar nenhum parâmetro.

Veja a seguir 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 desabilitar 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 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 booliano que indica se a verificação de integridade do banco de dados está desabilitada ou não.
DisableTracing Um valor booliano que indica se o rastreamento de OpenTelemetry está desabilitado ou não.
DisableRetry Um valor booliano 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.

Client checagens de saúde de integração

Por padrão, .NET.NET Aspireintegrações de cliente têm verificações de integridade habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também habilitam endpoints para verificação de saúde. Para obter mais informações, consulte:

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

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente registros, monitoramento e métricas, que às vezes são conhecidos como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro de Atividades

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

Rastreamento

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

  • OpenTelemetry. Instrumentation.EntityFrameworkCore

Métricas

A integração .NET AspireOracleEntity Framework Core atualmente dá suporte às seguintes métricas:

  • Microsoft.EntityFrameworkCore

Consulte também