.NET Aspire SQL Server Entity Framework Core integración

Incluye: Integración de alojamiento —&— Client integración

SQL Server es un sistema de administración de bases de datos relacional desarrollado por Microsoft. La .NET AspireSQL ServerEntity Framework Core integración permite conectarse a instancias existentes de SQL Server o crear nuevas instancias a partir de .NET con la imagen de contenedor de mcr.microsoft.com/mssql/server.

Integración de hospedaje

La integración de alojamiento SQL Server modela los modelos de integración del servidor como el tipo SqlServerServerResource y la base de datos como el tipo SqlServerDatabaseResource. Para acceder a estos tipos y API, agregue el 📦Aspire.Hosting.SqlServer paquete NuGet en el proyecto de host de la aplicación .

dotnet add package Aspire.Hosting.SqlServer

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

Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en las aplicaciones .NET.

Agregar el recurso SQL Server y el recurso de base de datos

En el proyecto host de la aplicación, utilice AddSqlServer para agregar y devolver un constructor de recursos SQL Server. Encadene una llamada al generador de recursos devuelto a AddDatabasepara agregar el recurso de base de datos SQL Server.

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de mcr.microsoft.com/mssql/server, crea una nueva instancia de SQL Server en el equipo local. Se usa una referencia al generador de recursos de SQL Server (la variable sql) para agregar una base de datos. La base de datos se denomina database y, a continuación, se agrega al ExampleProject.

Al añadir un recurso de base de datos al modelo de la aplicación, la base de datos se crea si aún no existe. La creación de la base de datos depende de las APIs de eventos del anfitrión de la aplicación, específicamente ResourceReadyEvent. En otras palabras, cuando el recurso sql está listo, se genera el evento y se crea el recurso de base de datos.

El recurso SQL Server incluye credenciales predeterminadas con un username de sa y un password aleatorio generado mediante el método CreateDefaultPasswordParameter.

Cuando se ejecuta el host de la aplicación, la contraseña se almacena en el almacén de secretos del host de la aplicación. Se agrega a la sección Parameters, por ejemplo:

{
  "Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}

El nombre del parámetro es sql-password, pero realmente solo da formato al nombre del recurso con un sufijo -password. Para obtener más información, consulte Almacenamiento seguro de secretos de aplicaciones en desarrollo en ASP.NET Core y Adición de recurso SQL Server con parámetros.

El método WithReference configura una conexión en el ExampleProject denominado database.

Añadir SQL Server recurso con scripts de base de datos

De forma predeterminada, cuando añades un SqlServerDatabaseResource, se basa en el siguiente script SQL para crear la base de datos:

IF
(
    NOT EXISTS
    (
        SELECT 1
        FROM sys.databases
        WHERE name = @DatabaseName
    )
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];

Para modificar el script predeterminado, encadene una llamada al método WithCreationScript en el creador de recursos de la base de datos.

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var databaseName = "app-db";
var creationScript = $$"""
    IF DB_ID('{{databaseName}}') IS NULL
        CREATE DATABASE [{{databaseName}}];
    GO

    -- Use the database
    USE [{{databaseName}}];
    GO

    -- Create the todos table
    CREATE TABLE todos (
        id INT PRIMARY KEY IDENTITY(1,1),        -- Unique ID for each todo
        title VARCHAR(255) NOT NULL,             -- Short description of the task
        description TEXT,                        -- Optional detailed description
        is_completed BIT DEFAULT 0,              -- Completion status
        due_date DATE,                           -- Optional due date
        created_at DATETIME DEFAULT GETDATE()    -- Creation timestamp
    );
    GO

    """;

var db = sql.AddDatabase(databaseName)
            .WithCreationScript(creationScript);

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

El ejemplo anterior crea una base de datos llamada app_db con una única tabla todos. El script SQL se ejecuta cuando se crea el recurso de base de datos. El script se pasa como una cadena al método WithCreationScript, que luego se ejecuta en el contexto del recurso SQL Server.

Agregar recurso SQL Server con un volumen de datos

Para agregar un volumen de datos al recurso de SQL Server, llame al método WithDataVolume en el recurso SQL Server:

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataVolume();

var db = sql.AddDatabase("database");

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

El volumen de datos se usa para persistir los datos correspondientes a SQL Server fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /var/opt/mssql dentro del contenedor SQL Server y, si no se proporciona un parámetro name, el nombre se genera de manera aleatoria. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a bind mounts, consulte la Docker documentación: Volúmenes.

Adición de recurso SQL Server con montaje mediante enlace de datos

Para agregar una montura de enlace de datos al recurso de SQL Server, llame al método WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataBindMount(source: @"C:\SqlServer\Data");

var db = sql.AddDatabase("database");

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

Los montajes de enlace de datos dependen del sistema de archivos del equipo host para preservar los datos de SQL Server cada vez que se reinicia el contenedor. El punto de montaje de enlace de datos se monta en la ruta C:\SqlServer\Data en Windows (o /SqlServer/Data en Unix) en el equipo host dentro del contenedor SQL Server. Para obtener más información sobre los montajes vinculados de datos, consulte la documentación Docker: Montajes vinculados.

Añadir recurso SQL Server con parámetros

Cuando quiera proporcionar explícitamente la contraseña usada por la imagen de contenedor, puede proporcionar estas credenciales como parámetros. Considere el siguiente ejemplo alternativo:

var builder = DistributedApplication.CreateBuilder(args);

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

var sql = builder.AddSqlServer("sql", password);
var db = sql.AddDatabase("database");

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

Para obtener más información sobre cómo proporcionar parámetros, consulte Parámetros externos.

Conexión a recursos de base de datos

Cuando se ejecuta el host de la aplicación .NET.NET Aspire, se puede acceder a los recursos de base de datos del servidor desde herramientas externas, como SQL Server Management Studio (SSMS) o MSSQL para Visual Studio Code. La cadena de conexión del recurso de base de datos está disponible en las variables de entorno de recursos dependientes y se puede acceder a ella mediante el panel .NET.NET Aspire: de Detalles del recurso. La variable de entorno se denomina ConnectionStrings__{name} donde {name} es el nombre del recurso de base de datos, en este ejemplo se database. Use la cadena de conexión para conectarse al recurso de base de datos desde herramientas externas. Imagine que tiene una base de datos denominada todos con una sola tabla de dbo.Todos.

Comprobaciones de estado de la integración de hospedaje

La integración de hospedaje SQL Server agrega automáticamente una comprobación de estado para el recurso SQL Server. La verificación de salud comprueba que el SQL Server está en funcionamiento y que se puede establecer una conexión con él.

La integración de hospedaje se basa en el paquete NuGet 📦 AspNetCore.HealthChecks.SqlServer.

integración Client

Para empezar a trabajar con la integración .NET AspireSQL ServerEntity Framework Core, instale el paquete NuGet 📦Aspire.Microsoft.EntityFrameworkCore.SqlServer en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa el cliente SQL ServerEntity Framework Core.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en las aplicaciones .NET.

Añadir SQL Server contexto de base de datos

En el archivo Program.cs de su proyecto que usa el cliente, invoque el método de extensión AddSqlServerDbContext en cualquier IHostApplicationBuilder para registrar un DbContext a utilizar mediante el contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddSqlServerDbContext<ExampleDbContext>(connectionName: "database");

Para recuperar el objeto ExampleDbContext de un servicio:

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

Para obtener más información sobre la inyección de dependencias, consulte .NET inyección de dependencias.

Enriquecer el contexto de la base de datos de SQL Server

Es posible que prefiera usar el método de Entity Framework estándar para obtener un contexto de base de datos y agregarlo al contenedor de inserción de dependencias:

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

Tiene más flexibilidad al crear el contexto de la base de datos de esta manera, por ejemplo:

• Puede reutilizar el código de configuración existente para el contexto de la base de datos sin volver a escribirlo para .NET.NET Aspire.
• Puede utilizar interceptores Entity Framework Core para modificar operaciones de base de datos.
• Puede optar por no usar la agrupación de contextos Entity Framework Core, lo cual podría funcionar mejor en algunas circunstancias.

Si usa este método, puede mejorar el contexto de la base de datos con reintentos de estilo .NET.NET Aspire, comprobaciones de estado, registro y características de telemetría llamando al método EnrichSqlServerDbContext:

builder.EnrichSqlServerDbContext<ExampleDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30; // seconds
    });

El parámetro settings es una instancia de la clase MicrosoftEntityFrameworkCoreSqlServerSettings.

Configuración

La integración de .NET AspireSQL ServerEntity Framework Core proporciona varios enfoques y opciones de configuración para cumplir los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, proporcione el nombre de la cadena de conexión al llamar a builder.AddSqlServerDbContext<TContext>():

builder.AddSqlServerDbContext<ExampleDbContext>("sql");

La cadena de conexión se obtiene de la sección de configuración ConnectionStrings.

{
  "ConnectionStrings": {
    "sql": "Data Source=myserver;Initial Catalog=master"
  }
}

El EnrichSqlServerDbContext no usará la sección de configuración de ConnectionStrings, ya que espera que el DbContext esté registrado en el momento de ser llamado.

Para obtener más información, consulte el ConnectionString.

Uso de proveedores de configuración

La integración .NET AspireSQL ServerEntity Framework Core es compatible con Microsoft.Extensions.Configuration. Carga el MicrosoftEntityFrameworkCoreSqlServerSettings desde archivos de configuración como appsettings.json mediante la clave Aspire:Microsoft:EntityFrameworkCore:SqlServer. Si ha configurado las configuraciones en la sección Aspire:Microsoft:EntityFrameworkCore:SqlServer, simplemente puede llamar al método sin pasar ningún parámetro.

A continuación se muestra un ejemplo de un appsettings.json archivo que configura algunas de las opciones disponibles:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "SqlServer": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "DisableMetrics": false
        }
      }
    }
  }
}

Utilice configuraciones en línea

También puede pasar Action<MicrosoftEntityFrameworkCoreSqlServerSettings> delegado para configurar algunas o todas las opciones directamente, por ejemplo, para desactivar las métricas.

builder.AddSqlServerDbContext<YourDbContext>(
    "sql",
    static settings =>
        settings.DisableMetrics = true);

Configura múltiples conexiones de DbContext

Si desea registrar más de una DbContext con una configuración diferente, puede usar el nombre de la sección de configuración $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}". La configuración json tendría el siguiente aspecto:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
          "SqlServer": {
            "ConnectionString": "YOUR_CONNECTIONSTRING",
            "DbContextPooling": true,
            "DisableHealthChecks": true,
            "DisableTracing": true,
            "DisableMetrics": false,
          "AnotherDbContext": {
            "ConnectionString": "AnotherDbContext_CONNECTIONSTRING",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

A continuación, llamar al método AddSqlServerDbContext con un parámetro de tipo AnotherDbContext cargaría la configuración desde la sección Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext.

builder.AddSqlServerDbContext<AnotherDbContext>("another-sql");

Opciones de configuración

Estas son las opciones configurables con los valores predeterminados correspondientes:

Client verificaciones de estado de la integración

De forma predeterminada, .NET.NET Aspirelas integraciones de cliente tienen habilitadas comprobaciones de estado para todos los servicios. Del mismo modo, muchas .NET.NET Aspireintegraciones de hospedaje también habilitan los endpoints de verificación de salud. Para obtener más información, consulte:

• .NET comprobaciones de estado de la aplicación en C#
• Chequeos de salud en ASP.NET Core

De forma predeterminada, la .NET Aspire integración de Sql ServerEntity Framework Core controla lo siguiente:

• Agrega el DbContextHealthCheck, que llama al método EF Core de CanConnectAsync. El nombre de la comprobación de salud coincide con el nombre del tipo TContext.
• Se integra con el punto de conexión HTTP /health, que especifica que todas las comprobaciones de estado registradas deben aprobarse para que la aplicación se considere lista para aceptar tráfico.

Observabilidad y telemetría

.NET .NET Aspire Las integraciones configuran automáticamente el registro de eventos, el seguimiento y las métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las funciones de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección de configuración .

Registro

La integración de .NET AspireSQL ServerEntity Framework Core usa las siguientes categorías de registro:

• 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

Rastreo

La integración de .NET AspireSQL ServerEntity Framework Core emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

• OpenTelemetry. Instrumentación.EntityFrameworkCore

Métricas

La integración de .NET AspireSQL ServerEntity Framework Core emitirá las siguientes métricas mediante 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

Consulte también

• Azure Documentación de SQL Database
• integraciones .NET.NET Aspire
• .NET Aspire GitHub Repo