integración de .NET AspireSQL Server

Incluye:integración de hospedaje y integraciónClient

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

Integración de hospedaje

El modelo de integración de alojamiento SQL Server representa server como tipo SqlServerServerResource y la base de datos como 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 Manage package dependencies in .NET applications.

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

En el proyecto host de la aplicación, llame a AddSqlServer para agregar y devolver un generador de recursos de 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>()
       .WithReference(db)
       .WaitFor(db);

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

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. 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 aplicación en desarrollo en ASP.NET Core y Agregar SQL Server recurso con parámetros.

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

Añadir el 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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

El volumen de datos se usa para almacenar los datos de SQL Server fuera del ciclo de vida del contenedor. El volumen de datos se monta en la ruta de acceso /var/opt/mssql del contenedor de SQL Server y, cuando no se proporciona un parámetro name, el nombre se genera de forma aleatoria. Para más información sobre los volúmenes de datos y por qué se prefieren a montajes enlazados, consulte la documentación de Docker: Volúmenes.

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

Para añadir un montaje de enlace de datos al recurso 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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

Los montajes de enlace de datos dependen del sistema de archivos del equipo host para conservar los datos de SQL Server en los reinicios del contenedor. El montaje de enlace de datos se monta en la ruta C:\SqlServer\Data en Windows (o /SqlServer/Data en Unix) en el equipo host en el contenedor SQL Server. Para obtener más información sobre los montajes de enlace de datos, consulte Docker documentos: Enlazar montajes.

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.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

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 Aspire, se puede acceder a los recursos de base de datos del serverdesde herramientas externas, como SQL Server Management Studio (SSMS) o Azure Data Studio. 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.

Hospedaje de comprobaciones de estado de integración

La integración de hospedaje SQL Server agrega automáticamente una verificación del estado para el recurso de SQL Server. La comprobación de estado verifica que el SQL Server se está ejecutando 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 de Client

Para empezar a trabajar con la integración de .NET AspireSQL Serverclient, instale el paquete NuGet de 📦Aspire.Microsoft.Data.SqlClient en el proyecto que consume client, es decir, el proyecto de la aplicación que usa el SQL Serverclient. La integración de SQL Serverclient registra una instancia de SqlConnection que puede usar para interactuar con SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

Agregar SQL Serverclient

En el archivo Program.cs del proyecto que utiliza client, llame al método de extensión AddSqlServerClient en cualquier IHostApplicationBuilder para registrar un SqlConnection para su uso mediante el contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddSqlServerClient(connectionName: "database");

A continuación, puede recuperar la instancia de SqlConnection mediante inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

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

Agregar SQL Serverclient con clave

Puede haber situaciones en las que quiera registrar varias instancias de SqlConnection con nombres de conexión diferentes. Para registrar clientes de SQL Server con clave, llame al método AddKeyedSqlServerClient:

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

A continuación, puede recuperar las instancias de SqlConnection mediante la inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

Para obtener más información sobre los servicios claveados, consulte .NET inserción de dependencias: Servicios claveados.

Configuración

La integración de .NET AspireSQL Server proporciona varias opciones para configurar la conexión en función de 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, puede proporcionar el nombre de la cadena de conexión al llamar al método AddSqlServerClient:

builder.AddSqlServerClient(connectionName: "sql");

A continuación, la cadena de conexión se recupera de la sección de configuración de ConnectionStrings:

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

Para obtener más información sobre cómo dar formato a esta cadena de conexión, consulte el ConnectionString.

Uso de proveedores de configuración

La integración de .NET AspireSQL Server admite Microsoft.Extensions.Configuration. Carga el MicrosoftDataSqlClientSettings desde la configuración mediante la clave Aspire:Microsoft:Data:SqlClient. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

Para ver el esquema completo de integración SQL ServerclientJSON, consulte Aspire.Microsoft.Data.SqlClient/ConfigurationSchema.json.

Usa delegados insertados

También puede pasar el delegado de Action<MicrosoftDataSqlClientSettings> configureSettings para configurar algunas o todas las opciones directamente en el código, por ejemplo, para deshabilitar las comprobaciones de estado desde el código.

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

verificaciones de salud de integración de Client

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan las comprobaciones de estado de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

La integración de .NET AspireSQL Server:

• Agrega la comprobación de estado cuando MicrosoftDataSqlClientSettings.DisableHealthChecks es false, que intenta conectarse al SQL Server.
• Se integra con el endpoint HTTP de /health, el cual especifica que todas las comprobaciones de estado registradas deben superarse para que la aplicación se considere lista para aceptar tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones establecen automáticamente las configuraciones de registro, seguimiento y 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 características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.

Registro

Actualmente, la integración de .NET AspireSQL Server no permite el registro por defecto debido a las limitaciones de la Microsoft.Data.SqlClient.

Trazado

La integración de .NET AspireSQL Server emite las siguientes actividades de seguimiento mediante OpenTelemetry:

• OpenTelemetry.Instrumentation.SqlClient

Métricas

La integración de .NET AspireSQL Server emitirá las métricas siguientes mediante OpenTelemetry:

• Microsoft.Data.SqlClient.EventSource
  • active-hard-connections
  • hard-connects
  • hard-disconnects
  • active-soft-connects
  • soft-connects
  • soft-disconnects
  • number-of-non-pooled-connections
  • number-of-pooled-connections
  • number-of-active-connection-pool-groups
  • number-of-inactive-connection-pool-groups
  • number-of-active-connection-pools
  • number-of-inactive-connection-pools
  • number-of-active-connections
  • number-of-free-connections
  • number-of-stasis-connections
  • number-of-reclaimed-connections

Consulte también

• Azure SQL Base de datos
• SQL Server
• contenedores de base de datos de ejemplo .NET.NET Aspire
• .NET .NET Aspire integraciones
• .NET Aspire GitHub del repositorio