Compartir a través de

integración .NET AspireSQL Server

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

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

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

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 tu proyecto anfitrión de la aplicación, llama a AddSqlServer para añadir 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();

Nota

El contenedor de SQL Server tarda en arrancar, por lo que es mejor usar una vida útil persistente para evitar reinicios innecesarios. Para obtener más información, consulte ciclo de vida de los recursos del contenedor.

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 no existe ya. La creación de la base de datos depende de las API de eventos del host de la aplicación, específicamente ResourceReadyEvent. En otras palabras, cuando el recurso sql está listo, se lanza 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 anfitrión de la aplicación, la contraseña se almacena en el almacén secreto del anfitrión 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.

Sugerencia

Si prefiere conectarse a un SQL Serverexistente, llame a AddConnectionString en su lugar. Para obtener más información, vea Hacer referencia a los recursos existentes.

Añadir SQL Server recurso con scripts de la 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 generador 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 sola tabla todos. El script SQL se ejecuta cuando se crea el recurso de la base de datos. El guion 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 almacenar los datos de SQL Server fuera del ciclo de vida del contenedor. El volumen de datos se monta en la ruta /var/opt/mssql dentro del contenedor SQL Server y, cuando no se proporciona un parámetro name, el nombre se genera aleatoriamente. 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.

Advertencia

La contraseña se almacena en el volumen de datos. Cuando se utiliza un volumen de datos y cambia la contraseña, no funcionará hasta que se elimine el volumen.

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

Importante

Los montajes de enlace de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen mejor rendimiento, portabilidad y seguridad, por lo que son más apropiados para entornos de producción. Sin embargo, los montajes enlazados permiten el acceso directo y la modificación de archivos en el sistema anfitrión, lo cual es ideal para el desarrollo y las pruebas donde se requieren cambios en tiempo real.

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.

Para conectarse al recurso de base de datos desde SQL Server Management Studio, siga estos pasos:

  1. Abra SSMS.

  2. En el cuadro de diálogo Conectarse a Server, seleccione la pestaña Parámetros de conexión adicionales.

  3. Pegue la cadena de conexión en el campo Parámetros de conexión adicionales y seleccione Conectar.

    SQL Server Management Studio: Conectar a Server diálogo.

  4. Si está conectado, puede ver el recurso de base de datos en el Explorador de objetos de :

    SQL Server Management Studio: conectado a la base de datos.

Para obtener más información, consulte SQL Server Management Studio: Conexión a un servidor.

Comprobaciones de estado de la integración de hospedaje

La integración de hospedaje SQL Server agrega automáticamente una verificación del estado para el recurso de 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 de cliente de .NET AspireSQL Server, instale el paquete NuGet 📦Aspire.Microsoft.Data.SqlClient en el proyecto cliente-consumidor, es decir, el proyecto de la aplicación que usa el cliente de SQL Server. La integración de cliente SQL Server registra una instancia de SqlConnection que puede usar para interactuar con SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

Agregar cliente SQL Server

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

builder.AddSqlServerClient(connectionName: "database");

Sugerencia

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso de base de datos SQL Server en el proyecto host de la aplicación. Es decir, cuando se llama a AddDatabase y se proporciona un nombre de database ese mismo nombre se debe usar al llamar a AddSqlServerClient. Para obtener más información, consulte SQL Server.

A continuación, puede recuperar la instancia SqlConnection usando la 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.

Adición de un cliente de SQL Server 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");

Importante

Cuando se usan servicios con claves, se espera que el recurso de SQL Server configure dos bases de datos con nombre, una para el mainDb y otra para la loggingDb.

A continuación, puede recuperar las instancias de SqlConnection usando 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 con clave, consulte .NET Inserción de Dependencias: Servicios con Clave.

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 usando 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 obtener el esquema completo SQL Server de integración del cliente JSON, consulte Aspire.Microsoft.Data.SqlClient/ConfigurationSchema.json.

Utiliza delegados en línea

También puede pasar el delegado Action<MicrosoftDataSqlClientSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar desde el código las comprobaciones de salud:

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

Client verificaciones de estado de la integración

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

La .NET AspireSQL Server integración:

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

Rastreo

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