From 8c27165826118d4d808a3a2e133b5f8f212ce984 Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 27 Feb 2024 08:43:46 -0600 Subject: [PATCH] Add new `Aspire.Oracle.EntityFrameworkCore` component. (#438) * Initial write up for the Oracle component * LGTM * Fix h1 * Fix list * remove cosmos ref --- .../oracle-entity-framework-component.md | 177 ++++++++++++++++++ docs/toc.yml | 2 + 2 files changed, 179 insertions(+) create mode 100644 docs/database/oracle-entity-framework-component.md diff --git a/docs/database/oracle-entity-framework-component.md b/docs/database/oracle-entity-framework-component.md new file mode 100644 index 000000000..36bb2d110 --- /dev/null +++ b/docs/database/oracle-entity-framework-component.md @@ -0,0 +1,177 @@ +--- +title: Oracle Entity Framework Component +description: Oracle Entity Framework Component +ms.date: 02/26/2024 +--- + +# .NET Aspire Oracle Entity Framework Component + +In this article, you learn how to use the The .NET Aspire Oracle EntityFrameworkCore component. The `Aspire.Oracle.EntityFrameworkCore` library is used to register a as a singleton in the DI container for connecting to Oracle databases. It also enables connection pooling, retries, health checks, logging and telemetry. + +## Get started + +You need an Oracle database and connection string for accessing the database. To get started with the The .NET Aspire Oracle EntityFrameworkCore component, install the [Aspire.Oracle.EntityFrameworkCore](https://www.nuget.org/packages/Aspire.Oracle.EntityFrameworkCore) NuGet package. + +### [.NET CLI](#tab/dotnet-cli) + +```dotnetcli +dotnet add package Aspire.Oracle.EntityFrameworkCore --prerelease +``` + +### [PackageReference](#tab/package-reference) + +```xml + +``` + +--- + +For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). + +## Example usage + +In the _Program.cs_ file of your component-consuming project, call the extension to register a for use via the dependency injection container. + +```csharp +builder.AddOracleDatabaseDbContext("oracle"); +``` + +You can then retrieve the instance using dependency injection. For example, to retrieve the client from a service: + +```csharp +public class ExampleService(DbContext context) +{ + // Use context... +} +``` + +You might also need to configure specific options of Oracle database, or register a `DbContext` in other ways. In this case call the `EnrichOracleDatabaseDbContext` extension method, for example: + +```csharp +var connectionString = builder.Configuration.GetConnectionString("catalogdb"); + +builder.Services.AddDbContextPool( + dbContextOptionsBuilder => dbContextOptionsBuilder.UseOracle(connectionString)); + +builder.EnrichOracleDatabaseDbContext(); +``` + +## App host usage + +In your app host project, register an Oracle container and consume the connection using the following methods: + +```csharp +var freepdb1 = builder.AddOracleDatabase("oracle") + .AddDatabase("freepdb1"); + +var myService = builder.AddProject() + .WithReference(freepdb1); +``` + +The method configures a connection in the `MyService` project named `freepdb1`. In the _Program.cs_ file of `MyService`, the database connection can be consumed using: + +```csharp +builder.AddOracleDatabaseDbContext("freepdb1"); +``` + +## Configuration + +The .NET Aspire Oracle EntityFrameworkCore component provides multiple options to configure the database connection based on the requirements and conventions of your project. + +### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddOracleDatabaseDbContext()`: + +```csharp +builder.AddOracleDatabaseDbContext("myConnection"); +``` + +And then the connection string will be retrieved from the `ConnectionStrings` configuration section: + +```json +{ + "ConnectionStrings": { + "myConnection": "Data Source=TORCL;User Id=myUsername;Password=myPassword;" + } +} +``` + +The `EnrichOracleDatabaseDbContext` won't make use of the `ConnectionStrings` configuration section since it expects a `DbContext` to be registered at the point it is called. + +See the [ODP.NET documentation](https://www.oracle.com/database/technologies/appdev/dotnet/odp.html) for more information on how to format this connection string. + +### Use configuration providers + +The .NET Aspire Oracle EntityFrameworkCore component supports [Microsoft.Extensions.Configuration](https://learn.microsoft.com/dotnet/api/microsoft.extensions.configuration). It loads the `OracleEntityFrameworkCoreSettings` from configuration by using the `Aspire:Oracle:EntityFrameworkCore` key. + +The following example shows an _appsettings.json_ that configures some of the available options: + +```json +{ + "Aspire": { + "Oracle": { + "EntityFrameworkCore": { + "HealthChecks": false, + "Tracing": false, + "Metrics": true, + "Retry": true, + "Timeout": 30 + } + } + } +} +``` + +> [!TIP] +> The `Timeout` property is in seconds. When set as shown in the preceding example, the timeout is 30 seconds. + +### Use inline delegates + +You can also pass the `Action configureSettings` delegate to set up some or all the options inline, for example to disable health checks from code: + +```csharp +builder.AddOracleDatabaseDbContext( + "oracle", + static settings => settings.HealthChecks = false); +``` + +or + +```csharp +builder.EnrichOracleDatabaseDbContext( + static settings => settings.HealthChecks = false); +``` + +[!INCLUDE [component-health-checks](../includes/component-health-checks.md)] + +The The .NET Aspire Oracle EntityFrameworkCore component registers a basic health check that checks the database connection given a `TContext`. The health check is enabled by default and can be disabled using the `HealthChecks` property in the configuration. + +[!INCLUDE [component-observability-and-telemetry](../includes/component-observability-and-telemetry.md)] + +### Logging + +The The .NET Aspire Oracle EntityFrameworkCore component uses the following log categories: + +- `Microsoft.EntityFrameworkCore.Database.Command.CommandCreated` +- `Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting` +- `Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted` +- `Microsoft.EntityFrameworkCore.Database.Command.CommandError` + +### Tracing + +The The .NET Aspire Oracle EntityFrameworkCore component will emit the following tracing activities using OpenTelemetry: + +- OpenTelemetry.Instrumentation.EntityFrameworkCore + +### Metrics + +The The .NET Aspire Oracle EntityFrameworkCore component currently supports the following metrics: + +- Microsoft.EntityFrameworkCore + +## See also + +- [Entity Framework Core docs](/ef/core) +- [.NET Aspire components](../fundamentals/components-overview.md) +- [.NET Aspire GitHub repo](https://github.com/dotnet/aspire) diff --git a/docs/toc.yml b/docs/toc.yml index c16edc489..85c80b026 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -91,6 +91,8 @@ items: href: database/mysql-component.md - name: MongoDB component href: database/mongodb-component.md + - name: Oracle Database - EF Core component + href: database/oracle-entity-framework-component.md - name: Seed data in a database href: database/seed-database-data.md