Aspire SQL Server integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

SQL Server är ett relationsdatabashanteringssystem som utvecklats av Microsoft. Med integreringen AspireSQL Server kan du ansluta till befintliga SQL Server instanser eller skapa nya instanser från .NET med containeravbildningenmcr.microsoft.com/mssql/server.

Integrering av värdtjänster

Värdintegreringen SQL Server modellerar servern som av typen SqlServerServerResource och databasen som av typen SqlServerDatabaseResource. Om du vill komma åt dessa typer och API:er lägger du till 📦Aspire. Hosting.SqlServer NuGet-paketet i AppHost-projektet .

dotnet add package Aspire.Hosting.SqlServer

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

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET program.

Lägg till SQL Server resurs och databasresurs

I ditt AppHost-projekt använder du AddSqlServer för att lägga till och returnera en SQL Server resurskompilator. Länka ett anrop från den returnerade resursbyggaren till AddDatabaseför att lägga till SQL Server databasresurs.

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

När Aspire en containeravbildning läggs till i AppHost, som du ser i föregående exempel med avbildningen mcr.microsoft.com/mssql/server , skapas en ny SQL Server instans på den lokala datorn. En referens till din SQL Server resursbyggare (variabeln sql) används för att lägga till en databas. Databasen heter database och läggs sedan till i ExampleProject.

När du lägger till en databasresurs i appmodellen skapas databasen om den inte redan finns. Skapandet av databasen förlitar sig på AppHost-händelse-API:erna, särskilt ResourceReadyEvent. Med andra ord, när resursen sql är klar utlöses händelsen och databasresursen skapas.

Den SQL Server resursen innehåller standardautentiseringsuppgifter med en username av sa och en slumpmässig password som genereras med hjälp av metoden CreateDefaultPasswordParameter.

När AppHost körs lagras lösenordet i AppHosts hemliga arkiv. Det läggs till i avsnittet Parameters, till exempel:

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

Namnet på parametern är sql-password, men egentligen är det bara att formatera resursnamnet med ett -password suffix. Mer information finns i Säker lagring av apphemligheter under utveckling i ASP.NET Core och Lägg till SQL Server resurs med parametrar.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet database.

Lägga till SQL Server resurs med databasskript

När du lägger till ett SqlServerDatabaseResourceförlitar det sig som standard på följande SQL-skript för att skapa databasen:

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

Om du vill ändra standardskriptet kedjar du ett anrop till WithCreationScript metoden i databasresursverktyget:

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

I föregående exempel skapas en databas med namnet app_db med en enda todos tabell. SQL-skriptet körs när databasresursen skapas. Skriptet skickas som en sträng till WithCreationScript metoden, som sedan körs i resursens SQL Server kontext.

Lägga till SQL Server resurs med datavolym

Om du vill lägga till en datavolym i resursen SQL Server anropar du metoden WithDataVolume på den SQL Server resursen:

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

Datavolymen används för att bevara SQL Server data utanför containerns livscykel. Datavolymen monteras på sökvägen /var/opt/mssql i containern SQL Server och när en name parameter inte tillhandahålls genereras namnet slumpmässigt. Mer information om datavolymer och information om varför de föredras framför bindningsmonteringar finns i Docker dokument: Volymer.

Lägg till SQL Server resurs med databindningsmontering

Om du vill lägga till en databindningsknytpunkt till SQL Server-resursen, anropar du WithDataBindMount-metoden.

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

Databindningar förlitar sig på värddatorns filsystem för att spara SQL Server-data vid omstarter av containrar. Databindningsmonteringen monteras på sökvägen C:\SqlServer\Data i Windows (eller /SqlServer/Data på Unix) på värddatorn i SQL Server-containern. Mer information om databindningsmonteringar finns i Docker dokument: Bindningsmonteringar.

Lägga till SQL Server resurs med parametrar

När du uttryckligen vill ange lösenordet som används av containeravbildningen kan du ange dessa autentiseringsuppgifter som parametrar. Tänk dig följande alternativa exempel:

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

Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.

Ansluta till databasresurser

Aspire När AppHost körs kan serverns databasresurser nås från externa verktyg, till exempel SQL Server Management Studio (SSMS) eller MSSQL för Visual Studio Code. Anslutningssträngen för databasresursen är tillgänglig i miljövariablerna för beroende resurser och nås med hjälp av Aspire instrumentpanelen: Fönstret Resursinformation . Miljövariabeln heter ConnectionStrings__{name} där {name} är namnet på databasresursen. I det här exemplet är den database. Använd anslutningssträngen för att ansluta till databasresursen från externa verktyg. Anta att du har en databas med namnet todos med en enda dbo.Todos tabell.

Utförande av integreringshälsokontroller

SQL Server värdintegrering lägger automatiskt till en hälsokontroll för den SQL Server resursen. Hälsokontrollen verifierar att SQL Server körs och att en anslutning kan upprättas till den.

Värdintegreringen är beroende av NuGet-paketet 📦 AspNetCore.HealthChecks.SqlServer.

Använda med icke-program.NET

Värdintegrering SQL Server kan användas med alla programteknik, inte bara .NET program. När du använder WithReference för att referera till en SQL Server resurs matas anslutningsinformation automatiskt in som miljövariabler i det refererande programmet.

För program som inte använder klientintegrering kan du komma åt anslutningsinformationen via miljövariabler. Här är ett exempel på hur du konfigurerar miljövariabler för ett icke-program.NET :

var builder = DistributedApplication.CreateBuilder(args);

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

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

// Example: Configure a non-.NET application with SQL Server access
var app = builder.AddExecutable("my-app", "python", "app.py", ".")
    .WithReference(database) // Provides ConnectionStrings__myDatabase
    .WithEnvironment(context =>
    {
        // Additional individual connection details as environment variables
        context.EnvironmentVariables["SQL_SERVER"] = sql.Resource.PrimaryEndpoint.Property(EndpointProperty.Host);
        context.EnvironmentVariables["SQL_PORT"] = sql.Resource.PrimaryEndpoint.Property(EndpointProperty.Port);
        context.EnvironmentVariables["SQL_USERNAME"] = "sa";
        context.EnvironmentVariables["SQL_PASSWORD"] = sql.Resource.PasswordParameter;
        context.EnvironmentVariables["SQL_DATABASE"] = database.Resource.DatabaseName;
    });

builder.Build().Run();

Den här konfigurationen ger icke-programmet.NET flera miljövariabler:

• ConnectionStrings__myDatabase: Den fullständiga SQL Server anslutningssträngen
• SQL_SERVER: Värdnamnet/IP-adressen för SQL Server
• SQL_PORT: Portnumret som SQL Server lyssnar på
• SQL_USERNAME: Användarnamnet (vanligtvis sa för SQL Server)
• SQL_PASSWORD: Det dynamiskt genererade lösenordet
• SQL_DATABASE: Namnet på databasen

Ditt icke-program.NET kan sedan läsa dessa miljövariabler för att ansluta till SQL Server databasen med hjälp av lämplig databasdrivrutin för den tekniken (till exempel pyodbc för Python, node-mssql för Node.jseller database/sql med en SQL Server drivrutin för Go).

Client integrering

Kom igång med klientintegrering genom AspireSQL Server att 📦Aspireinstallera . Microsoft.Data.SqlClient NuGet-paketet i det klientkrävande projektet, dvs. projektet för programmet som använder SQL Server klienten. SQL Server-klientintegrering registrerar en SqlConnection instans som du kan använda för att interagera med SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

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

Lägg till SQL Server klient

I Program.cs-filen för ditt klientanvändande projekt anropar du AddSqlServerClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en SqlConnection för användning via beroendeinjektionsbehållaren. Metoden tar en parameter för anslutningsnamn.

builder.AddSqlServerClient(connectionName: "database");

Du kan sedan hämta SqlConnection-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till klient med nyckel SQL Server

Det kan finnas situationer där du vill registrera flera SqlConnection instanser med olika anslutningsnamn. Om du vill registrera nyckelade SQL Server klienter anropar du metoden AddKeyedSqlServerClient:

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

Sedan kan du hämta SqlConnection-instanser med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om nyckelade tjänster finns i .NET beroendeinmatning: Nyckelade tjänster.

Konfiguration

Den AspireSQL Server integreringen innehåller flera alternativ för att konfigurera anslutningen baserat på kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings-konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar metoden AddSqlServerClient:

builder.AddSqlServerClient(connectionName: "sql");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Mer information om hur du formaterar den här anslutningssträngen finns i ConnectionString.

Använda konfigurationsprovidrar

Aspire SQL Server-integreringen stöder Microsoft.Extensions.Configuration. Den läser in MicrosoftDataSqlClientSettings från konfigurationen med hjälp av Aspire:Microsoft:Data:SqlClient-nyckeln. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

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

Det fullständiga SQL Server klientintegreringsschemat JSON finns i Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Använd inline-delegater

Du kan också skicka delegering Action<MicrosoftDataSqlClientSettings> configureSettings för att konfigurera vissa eller alla alternativ inline, till exempel för att inaktivera hälsokontroller från kod.

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

Client hälsokontroller för integrering

Integreringar aktiverar som standard Aspirehälsokontroller för alla tjänster. Mer information finns i Aspire översikten över integreringar.

Integreringen AspireSQL Server:

• Lägger till hälsokontrollen när MicrosoftDataSqlClientSettings.DisableHealthChecks är false, vilken försöker ansluta till SQL Server.
• Integrerar med /health HTTP-slutpunkt, som anger att alla registrerade hälsokontroller ska passera för att appen ska anses vara redo att acceptera trafik.

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Konfiguration .

Skogsavverkning

Den AspireSQL Server integreringen aktiverar för närvarande inte loggning som standard på grund av begränsningar i Microsoft.Data.SqlClient.

Spårning

Aspire SQL Server-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• OpenTelemetry.Instrumentation.SqlClient

Mått

Integreringen AspireSQL Server genererar följande mått med hjälp av 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

Se även

• Azure SQL Database
• SQL Server
• Aspire exempel på databascontainrar
• Aspire Integrationer
• Aspire GitHub Repo
• Azure SQL & SQL ServerAspire -exempel