Aspire SQL Server integratie

Inclusief: —&— Client integratie

SQL Server is een relationeel databasebeheersysteem dat is ontwikkeld door Microsoft. Met de AspireSQL Server-integratie kunt u verbinding maken met bestaande SQL Server-instanties of nieuwe instanties maken vanuit .NET met de mcr.microsoft.com/mssql/server containerafbeelding.

Hostingintegratie

De SQL Server-hostingintegratie modelleert de server als het SqlServerServerResource-type en de database als het SqlServerDatabaseResource-type. Als u toegang wilt krijgen tot deze typen en API's, voegt u de 📦Aspire. Hosting.SqlServer NuGet-pakket in het AppHost-project .

dotnet add package Aspire.Hosting.SqlServer

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

SQL Server resource en databaseresource toevoegen

Roep in uw AppHost-project AddSqlServer aan om een SQL Server resourcebouwer toe te voegen en te retourneren. Verbind een oproep met de geretourneerde resource builder naar AddDatabaseom de databaseresource SQL Server toe te voegen.

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

Wanneer Aspire u een containerinstallatiekopieën toevoegt aan de AppHost, zoals wordt weergegeven in het vorige voorbeeld met de mcr.microsoft.com/mssql/server installatiekopieën, wordt er een nieuw SQL Server exemplaar op uw lokale computer gemaakt. Een verwijzing naar de SQL Server resourcebouwer (de sql variabele) wordt gebruikt om een database toe te voegen. De database heeft de naam database en wordt vervolgens toegevoegd aan de ExampleProject.

Wanneer u een databaseresource toevoegt aan het app-model, wordt de database gemaakt als deze nog niet bestaat. Het maken van de database is afhankelijk van de AppHost-gebeurtenis-API's, met name ResourceReadyEvent. Met andere woorden, wanneer de sql resource gereed is, wordt de gebeurtenis getriggerd en wordt de databaseresource gemaakt.

De SQL Server-resource bevat standaardreferenties met een username van sa en een willekeurige password die is gegenereerd met behulp van de CreateDefaultPasswordParameter-methode.

Wanneer de AppHost wordt uitgevoerd, wordt het wachtwoord opgeslagen in het geheime archief van AppHost. Deze wordt toegevoegd aan de sectie Parameters, bijvoorbeeld:

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

De naam van de parameter is sql-password, maar eigenlijk is het alleen het opmaken van de resourcenaam met een -password achtervoegsel. Voor meer informatie, zie Veilige opslag van app-geheimen in ontwikkeling in ASP.NET Core en SQL Server resource toevoegen met parameters.

De methode WithReference configureert een verbinding in de ExampleProject met de naam database.

Resource toevoegen SQL Server met databasescripts

Wanneer u een SqlServerDatabaseResourcetoevoegt, is het standaard afhankelijk van het volgende SQL-script om de database te maken:

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

Als u het standaardscript wilt wijzigen, koppelt u een aanroep aan de WithCreationScript methode in de opbouwfunctie voor databaseresources:

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

In het voorgaande voorbeeld wordt een database gemaakt met een naam app_db met één todos tabel. Het SQL-script wordt uitgevoerd wanneer de databaseresource wordt gemaakt. Het script wordt doorgegeven als een tekenreeks aan de WithCreationScript methode, die vervolgens wordt uitgevoerd in de context van de SQL Server resource.

SQL Server resource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de SQL Server-resource, roept u de methode WithDataVolume aan voor de SQL Server resource:

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

Het gegevensvolume wordt gebruikt om de SQL Server gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/opt/mssql pad in de SQL Server container en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Voor meer informatie over gegevensvolumes en waarom ze de voorkeur hebben boven bind mounts , zie Docker documentatie: Volumes.

SQL Server resource toevoegen met koppeling voor gegevensbinding

Als u een koppeling voor gegevensbinding wilt toevoegen aan de SQL Server-resource, roept u de WithDataBindMount methode aan:

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

Data-bind-mounts maken gebruik van het bestandssysteem van de hostmachine om de SQL Server-data bij herstarten van de container te behouden. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\SqlServer\Data in Windows (of /SqlServer/Data op Unix) op de hostcomputer in de SQL Server container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over de koppeling van gegevens.

SQL Server resource toevoegen met parameters

Wanneer u expliciet het wachtwoord wilt opgeven dat door de containerafbeelding wordt gebruikt, kunt u deze inloggegevens als parameters opgeven. Bekijk het volgende alternatieve voorbeeld:

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

Zie Externe parametersvoor meer informatie over het opgeven van parameters.

Verbinding maken met databasebronnen

Wanneer de Aspire AppHost wordt uitgevoerd, kunnen de databasebronnen van de server worden geopend vanuit externe hulpprogramma's, zoals SQL Server Management Studio (SSMS) of MSSQL voor Visual Studio Code. De verbindingsreeks voor de databaseresource is beschikbaar in de omgevingsvariabelen van afhankelijke resources en kan worden geopend via het Aspire dashboard: het deelvenster Resourcedetails. De omgevingsvariabele heet ConnectionStrings__{name} waar {name} de naam van de databaseresource is, in dit voorbeeld is deze database. Gebruik de verbindingsreeks om verbinding te maken met de databaseresource vanuit externe hulpprogramma's. Stel dat u een database hebt met de naam todos met één dbo.Todos tabel.

Gezondheidscontroles voor hostingintegratie

De SQL Server hostingintegratie voegt automatisch een statuscontrole toe voor de SQL Server resource. De gezondheidscontrole controleert of de SQL Server draait en of er een verbinding kan worden gemaakt.

De hostingintegratie is afhankelijk van het 📦 AspNetCore.HealthChecks.SqlServer NuGet-pakket.

Gebruik met niet-.NET-toepassingen

De SQL Server hostingintegratie kan worden gebruikt met elke toepassingstechnologie, niet alleen .NET toepassingen. Wanneer u WithReference gebruikt om naar een SQL Server-resource te verwijzen, wordt verbindingsinformatie automatisch als omgevingsvariabelen in de verwijzende toepassing ingevoegd.

Voor toepassingen die de clientintegratie niet gebruiken, hebt u toegang tot de verbindingsgegevens via omgevingsvariabelen. Hier is een voorbeeld van hoe u omgevingsvariabelen configureert voor een applicatie zonder .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();

Deze configuratie biedt de niet-.NET-applicatie verschillende omgevingsvariabelen:

• ConnectionStrings__myDatabase: De volledige SQL Server verbindingsreeks
• SQL_SERVER: de hostnaam/het IP-adres van de SQL Server
• SQL_PORT: Het poortnummer waarop SQL Server wordt geluisterd
• SQL_USERNAME: De gebruikersnaam (meestal sa voor SQL Server)
• SQL_PASSWORD: Het dynamisch gegenereerde wachtwoord
• SQL_DATABASE: De naam van de database

Uw niet-toepassing.NET kan deze omgevingsvariabelen vervolgens lezen om verbinding te maken met de SQL Server database met behulp van het juiste databasestuurprogramma voor die technologie (bijvoorbeeld pyodbc voor Pythonnode-mssql, of Node.jsdatabase/sql met een SQL Server stuurprogramma voor Go).

Client integratie

Installeer het NuGet-pakket Aspire in het project dat de client gebruikt, dat wil zeggen, het project voor de toepassing die gebruikmaakt van de SQL Server-client, om aan de slag te gaan met de 📦Aspire-clientintegratie. De SQL Server-clientintegratie registreert een SqlConnection exemplaar dat u kunt gebruiken om met SQL Serverte communiceren.

dotnet add package Aspire.Microsoft.Data.SqlClient

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

SQL Server-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddSqlServerClient-extensiemethode aan op een IHostApplicationBuilder om een SqlConnection te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddSqlServerClient(connectionName: "database");

Vervolgens kunt u het SqlConnection exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Voeg klant met sleutel SQL Server toe

Er kunnen situaties zijn waarin u meerdere SqlConnection exemplaren met verschillende verbindingsnamen wilt registreren. Om kliënten met sleutel SQL Server te registreren, roept u de methode AddKeyedSqlServerClient op.

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

Vervolgens kunt u de SqlConnection instanties ophalen via afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over sleutelservices, zie .NET afhankelijkheidsinjectie: sleutelservices.

Configuratie

De AspireSQL Server-integratie biedt meerdere opties voor het configureren van de verbinding op basis van de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van de AddSqlServerClient methode:

builder.AddSqlServerClient(connectionName: "sql");

Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings configuratiesectie:

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

Zie de ConnectionStringvoor meer informatie over het opmaken van deze verbindingsreeks.

Configuratieproviders gebruiken

De AspireSQL Server-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de MicrosoftDataSqlClientSettings vanuit de configuratie door gebruik te maken van de Aspire:Microsoft:Data:SqlClient-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:

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

Zie voor het volledige SQL Server clientintegratieschema JSON, Aspire.Microsoft.Data.SqlClient/ConfigurationSchema.json.

Gebruik inline delegaten

U kunt ook de Action<MicrosoftDataSqlClientSettings> configureSettings gedelegeerde doorgeven om enkele of alle opties direct in te stellen, bijvoorbeeld om gezondheidscontroles vanuit de code uit te schakelen.

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

gezondheidscontroles voor integratie Client

Aspire Standaard schakelen integraties statuscontroles in voor alle services. Zie Aspire het overzicht van integraties voor meer informatie.

De AspireSQL Server-integratie:

• De gezondheidscontrole wordt toegevoegd wanneer MicrosoftDataSqlClientSettings.DisableHealthChecksfalseis, wat probeert verbinding te maken met de SQL Server.
• Integreert met het /health HTTP-eindpunt, waarmee alle geregistreerde gezondheidscontroles moeten slagen zodat de app als gereed wordt beschouwd voor het accepteren van verkeer.

Waarneembaarheid en telemetrie

Aspire Integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrische gegevens in, die ook wel de pijlers van waarneembaarheid worden genoemd. Zie het overzicht van integratieobserveerbaarheid en telemetrie voor meer informatie over integratieobserveerbaarheid en telemetrieAspire. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De integratie van AspireSQL Server schakelt logboekregistratie momenteel niet standaard in vanwege beperkingen van de Microsoft.Data.SqlClient.

Opsporing

De AspireSQL Server-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• OpenTelemetry.Instrumentation.SqlClient

Statistieken

De integratie van AspireSQL Server verzendt de volgende metrische gegevens met behulp van 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

Zie ook

• Azure SQL Database-
• SQL Server
• Aspire voorbeeld van databasecontainers
• Aspire Integraties
• Aspire GitHub Repo
• Azure SQL & SQL ServerAspire -voorbeelden