Delen via

integratie van .NET AspireSQL Server

  • Artikel

omvat:hosting-integratie en Client integratie

SQL Server is een relationeel databasebeheersysteem dat is ontwikkeld door Microsoft. Met de .NET 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 integratie van SQL Server 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 het NuGet-pakket 📦Aspire.Hosting.SqlServer toe aan het app-hostproject.

dotnet add package Aspire.Hosting.SqlServer

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

SQL Server resource en databaseresource toevoegen

Roep in uw app-hostproject 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>()
       .WithReference(db)
       .WaitFor(db);

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

Notitie

De SQL Server container start traag op, dus het is beter om een permanente levensduur te gebruiken om onnodige herstarts te voorkomen. Zie Levensduur van containerresourcesvoor meer informatie.

Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de mcr.microsoft.com/mssql/server-installatiekopie, 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. 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 app-host wordt uitgevoerd, wordt het wachtwoord opgeslagen in het geheime archief van de app-host. 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.

Fooi

Als u liever verbinding wilt maken met een bestaande SQL Server, roept u in plaats daarvan AddConnectionString aan. Raadpleeg bestaande bronnenvoor meer informatie.

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

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

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.

Waarschuwing

Het wachtwoord wordt opgeslagen in het gegevensvolume. Wanneer u een gegevensvolume gebruikt en als het wachtwoord wordt gewijzigd, werkt het pas als u het volume verwijdert.

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

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

Belangrijk

Koppelingsbestanden hebben beperkte functionaliteit in vergelijking met volumes, die betere prestaties, draagbaarheid, en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bindmounts bieden echter directe toegang tot en de mogelijkheid om bestanden op het hostsysteem te wijzigen, ideaal voor ontwikkeling en testen wanneer realtime wijzigingen nodig zijn.

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

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

Zie Externe parametersvoor meer informatie over het opgeven van parameters.

Verbinding maken met databasebronnen

Wanneer de .NET Aspire app-host wordt uitgevoerd, kunnen de databasebronnen van de serverworden geopend vanuit externe hulpprogramma's, zoals SQL Server Management Studio (SSMS) of Azure Data Studio. De verbindingsreeks voor de databaseresource is beschikbaar in de omgevingsvariabelen van afhankelijke resources en wordt geopend via het .NET.NET Aspire dashboard: Resourcedetails deelvenster. 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.

Voer de volgende stappen uit om vanuit SQL Server Management Studio verbinding te maken met de databaseresource:

  1. Open SSMS.

  2. Selecteer in het dialoogvenster Verbinding maken met Server het tabblad Aanvullende verbindingsparameters.

  3. Plak de verbindingsreeks in het veld Aanvullende verbindingsparameters en selecteer Verbinding maken.

    SQL Server Management Studio: Verbinding maken met Server dialoogvenster.

  4. Als u verbinding hebt, ziet u de databaseresource in de Objectverkenner:

    SQL Server Management Studio: Verbonden met database.

Zie SQL Server Management Studio: Verbinding maken met een servervoor meer informatie.

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

integratie van Client

Installeer de 📦Aspireom aan de slag te gaan met de .NET AspireSQL Serverclient-integratie. Microsoft.Data.SqlClient NuGet-pakket in het client-verbruikende project, dat wil bijvoorbeeld het project voor de toepassing die gebruikmaakt van de SQL Serverclient. De SQL Serverclient-integratie registreert een SqlConnection exemplaar dat u kunt gebruiken om met SQL Serverte communiceren.

dotnet add package Aspire.Microsoft.Data.SqlClient

SQL Server client toevoegen

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

builder.AddSqlServerClient(connectionName: "database");

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de SQL Server databaseresource in het app-hostproject. Met andere woorden, wanneer u AddDatabase aanroept en een naam opgeeft van database diezelfde naam moet worden gebruikt bij het aanroepen van AddSqlServerClient. Voor meer informatie, zie SQL Server-bron en databaseresource toevoegen.

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.

Sleutel-SQL Serverclient toevoegen

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

Belangrijk

Wanneer u sleutelservices gebruikt, wordt verwacht dat uw SQL Server resource twee benoemde databases heeft geconfigureerd, één voor de mainDb en één voor de 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 .NET 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 .NET AspireSQL Server-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de MicrosoftDataSqlClientSettings vanuit de configuratie met behulp 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
        }
      }
    }
  }
}

Voor het volledige SQL ServerclientJSON integratieschema, zie Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Inline gedelegeerden gebruiken

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

Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

De .NET 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

.NET .NET Aspire integraties automatisch configuraties voor logboekregistratie, tracering en metrische gegevens instellen, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. 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.

Logboekregistratie

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

Opsporing

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

  • OpenTelemetry.Instrumentation.SqlClient

Statistieken

De integratie van .NET 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