Gyorsútmutató: A Microsoft.Data.SqlClient használata egy ASP.NET Core alkalmazásban

Ebben a gyorsindításban egy ASP.NET Core minimális API-t építesz a Microsoft.Data.SqlClient 7.1.1 használatával.

Egy üres mappával, a .NET SDK-val, valamint egy SQL Server vagy Azure SQL adatbázissal kezded, amit a számítógépedről elérhetsz. A végeredmény egy webes API, amely hozzáad egy üzenetet egy táblához, és azonosító szerint olvassa vissza.

Útközben az alkalmazás:

  • Olvassa a kapcsolati karakterlánc-et az ASP.NET Core konfigurációból. A helyi fejlesztésnél az érték a felhasználói titkokból ered, így nem kerül a projektmappádba.
  • Regisztrál egy adatosztályt függőséginjektálással.
  • Megnyitja és lezárja a kapcsolatot minden kéréshez, így az alapértelmezett kapcsolati pool újra felhasználhatja a fizikai kapcsolatokat.
  • A kérés CancellationToken továbbítása minden adatbázishíváshoz.

Az alkalmazás ugyanazt a dbo.SqlClientQuickstart táblázatot használja, mint a Quickstart: Kapcsolódás és lekérdezés a Microsoft.Data.SqlClient használatával. Bármelyik gyorsútmutatót elvégezheted először.

Előfeltételek

A jelenlegi ASP.NET Core .NET-en fut, nem .NET Framework-en. A .NET Frameworkból származó meghajtó használatához lásd a .NET Framework projekteket.

Az adatbázis identitásának engedélyre van szüksége a csatlakozáshoz, valamint a táblázat létrehozásához, beillesztéséhez és kiválasztásához.

A projekt létrehozása

Egy üres mappában futtassa ezeket a parancsokat:

dotnet new web --framework net10.0 --name SqlClientWebQuickstart
cd SqlClientWebQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1
dotnet user-secrets init

dotnet user-secrets init hozzáadja a UserSecretsId-t a projektfájlhoz. Az ASP.NET Core csak akkor tölti be a felhasználói titkokat, amikor az alkalmazás a Development környezetben fut, ami a(z) dotnet run alapértelmezettje.

A kiterjesztési csomag biztosítja az illesztőprogram Microsoft Entra hitelesítési módjait. Ha az alkalmazásod csak SQL hitelesítést használ, kihagyhatod Microsoft.Data.SqlClient.Extensions.Azure. Ha mindkét csomagot használod, ügyelj arra, hogy a verziójuk azonos legyen.

Konfiguráld a kapcsolatot

Tárold a kapcsolati karakterlánc-et ConnectionStrings:Quickstart néven a felhasználói titkok között. A felhasználói titkok a felhasználói profilodban vannak tárolva, nem a projekt mappában, így nem kerülnek be a verziókezelésbe. Ne tegyél be jelszót vagy gyártási kapcsolati karakterlánc-et appsettings.json.

Válassz ki ezek közül az egyik kezdőpontot, és cseréld le a helykitöltőket. A dotnet user-secrets set parancsok PowerShell és Bash esetén egyszeres idézőjeleket használnak. A Parancssorban használj inkább dupla idézőjeleket, mert a Parancssor az egyszeres idézőjeleket a kulcs és az érték részeként tárolja.

Azure SQL with Microsoft Entra ID

Jelentkezz be egy Microsoft Entra azonosítóval, amely hozzáfér az adatbázishoz. Helyi fejlesztéshez használj fejlesztői eszközt, például az Azure CLI-t:

az login

Ezután tárold a kapcsolati karakterlánc-et. Másold le a pontos szerver- és adatbázisneveket az Azure SQL adatbázisból. Ugyanez a kapcsolati karakterlánc működik SQL adatbázisban is a Microsoft Fabric-ben, amikor az SQL adatbázis eleme szerver- és adatbázisnevét használod, ahogy az a konzol gyorsindításban le van írva.

dotnet user-secrets set 'ConnectionStrings:Quickstart' 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;Connect Timeout=30'

Ez a kapcsolati karakterlánc nem tartalmaz titkot. Active Directory Default helyben használja a fejlesztői bejelentkezését. Amikor telepíted az Azure App Service-re vagy az Azure Container Apps-re, adj adatbázis-hozzáférést az alkalmazás felügyelt identitásának, módosítsd az értéket erre: Authentication=Active Directory Managed Identity, és állítsd be a gazdagép konfigurációjában így: ConnectionStrings__Quickstart. További lehetőségekért lásd: Microsoft Entra-hitelesítés a Microsoft.Data.SqlClienttel.

Helyi SQL Server SQL hitelesítéssel

Tárold a kapcsolati karakterlánc egy helyi fejlesztői példányhoz, amelynek nincs megbízható tanúsítványa. Használj egyes idézőjeleket, hogy megakadályozd a PowerShell és a Bash számára a jelszóban lévő $ karakter kibővítését.

dotnet user-secrets set 'ConnectionStrings:Quickstart' 'Server=tcp:<server>,1433;Database=<database>;User ID=<user-id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Caution

TrustServerCertificate=true kihagyja a szerver tanúsítvány ellenőrzését. Csak egy helyi fejlesztési példánysal használd. Megosztott vagy éles SQL Server példányok esetén telepítsenek egy tanúsítványt, amiben az ügyfél megbízik, és távolítsák el TrustServerCertificate=true. További információ: Titkosítás és tanúsítványérvényesítés a Microsoft.Data.SqlClientben.

A kód hozzáadása

Cserélje le a Program.cs tartalmát ezzel a kóddal:

using System.Data;
using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<MessageStore>();

var app = builder.Build();

await app.Services.GetRequiredService<MessageStore>()
    .EnsureTableAsync(app.Lifetime.ApplicationStopping);

app.MapPost("/messages", async (
    NewMessage input, MessageStore store, CancellationToken cancellationToken) =>
{
    if (string.IsNullOrWhiteSpace(input.Text) || input.Text.Length > 200)
    {
        return Results.BadRequest("Text must be 1 to 200 characters.");
    }

    Message message = await store.AddAsync(input.Text, cancellationToken);
    return Results.Created($"/messages/{message.Id}", message);
});

app.MapGet("/messages/{id:int}", async (
    int id, MessageStore store, CancellationToken cancellationToken) =>
    await store.GetAsync(id, cancellationToken) is Message message
        ? Results.Ok(message)
        : Results.NotFound());

app.Run();

record NewMessage(string Text);

record Message(int Id, string Text, DateTimeOffset CreatedAt);

sealed class MessageStore(IConfiguration configuration)
{
    private readonly string _connectionString =
        configuration.GetConnectionString("Quickstart")
        ?? throw new InvalidOperationException(
            "Set the ConnectionStrings:Quickstart configuration value.");

    public async Task EnsureTableAsync(CancellationToken cancellationToken)
    {
        const string sql = """
            IF OBJECT_ID(N'dbo.SqlClientQuickstart', N'U') IS NULL
            BEGIN
                CREATE TABLE dbo.SqlClientQuickstart
                (
                    Id int IDENTITY(1, 1) PRIMARY KEY,
                    Message nvarchar(200) NOT NULL,
                    CreatedAt datetimeoffset NOT NULL
                        CONSTRAINT DF_SqlClientQuickstart_CreatedAt
                        DEFAULT sysdatetimeoffset()
                );
            END;
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        await command.ExecuteNonQueryAsync(cancellationToken);
    }

    public async Task<Message> AddAsync(
        string text, CancellationToken cancellationToken)
    {
        const string sql = """
            INSERT INTO dbo.SqlClientQuickstart (Message)
            OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt
            VALUES (@message);
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@message", SqlDbType.NVarChar, 200).Value = text;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        await reader.ReadAsync(cancellationToken);
        return new Message(
            reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2));
    }

    public async Task<Message?> GetAsync(
        int id, CancellationToken cancellationToken)
    {
        const string sql = """
            SELECT Id, Message, CreatedAt
            FROM dbo.SqlClientQuickstart
            WHERE Id = @id;
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@id", SqlDbType.Int).Value = id;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        return await reader.ReadAsync(cancellationToken)
            ? new Message(
                reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2))
            : null;
    }
}

Az alkalmazás futtatása

Indítsd az alkalmazást egy fix porton:

dotnet run --urls http://localhost:5000

Indításkor az alkalmazás létrehozza a táblát, ha az nem létezik. Amikor az alkalmazás készen áll, a kimenet tartalmazza az alábbi sorokat:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Ha az alkalmazás nem éri el az adatbázist, akkor az indításkor SqlException hibával leáll. A gyakori okokról lásd: Hibaelhárítás.

Az API meghívása

Hagyd az alkalmazást működésben, és nyiss meg egy második terminált. Adj hozzá egy üzenetet egy POST kéréssel, majd olvasd vissza azonosító alapján egy GET kéréssel. Ha a táblában már vannak sorok, például a konzol gyorsindításából, cseréld le a GET kérésben a 1 elemet a POST kérésed által visszaadott id elemre.

PowerShell esetén:

Invoke-RestMethod -Method Post -Uri http://localhost:5000/messages -ContentType application/json -Body (@{ text = 'Hello from ASP.NET Core' } | ConvertTo-Json)
Invoke-RestMethod http://localhost:5000/messages/1

A PowerShell minden JSON választ táblázatként formáz. Az első sor a 201 Created POST kérésre adott válasz, a második sor pedig a GET válasz:

id text                    createdAt
-- ----                    ---------
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00

A Windows PowerShell 5.1 a(z) createdAt karakterláncot jeleníti meg az API által visszaadott karakterláncként. A PowerShell 7 azt helyi idő szerinti dátummá konvertálja, például 10/20/2026 7:04:43 PM.

A Windows PowerShellben a curl a Invoke-WebRequest aliasa, amely nem fogadja el a curl opciókat. Használd a PowerShell parancsokat, vagy a Parancssorból futtasd el curl.exe.

Parancssorhoz:

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d "{\"text\":\"Hello from ASP.NET Core\"}"
curl http://localhost:5000/messages/1

A parancssorban nem kezeli az egyszeres idézőjeleket idézőjel-karakterként, így a JSON-törzs dupla idézőjeleket használ, amelyek fordított perjelekkel escape-elve vannak. Minden parancs kinyomtatja a JSON választ:

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}

Bash esetén:

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d '{"text":"Hello from ASP.NET Core"}'
curl http://localhost:5000/messages/1

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}

Az azonosítóid és időbélyegjeid eltérnek. Ha először a konzol gyorsindítást futtattad, az azonosítók az ottani sorok után folytatódnak. Egy nem létező azonosítóra irányuló kérés 404 Not Found-t ad vissza. Üres üzenet esetén 400 Bad Request tér vissza.

Nyomja meg a Ctrl+C gombot az első terminálban, hogy megállítsa az alkalmazást.

A kód működése

  • Az alkalmazás a(z) MessageStore elemet szinglitonként regisztrálja. Csak a kapcsolati karakterláncet tartalmazza, amelyet a IConfiguration helyről olvas be egyszer. Nem tartja fenn a kapcsolatot.
  • Minden módszer létrehoz egy SqlConnection-t, megnyitja, futtat egy parancsot, majd a(z) await using használatával felszabadítja. A felszabadítás visszaadja a fizikai kapcsolatot a kapcsolatpoolba, és a következő kérés újra felhasználja. A kapcsolat-összevonás alapértelmezetten be van kapcsolva, így nem kell konfigurálni. A hangolási beállításokkal kapcsolatban lásd: SQL Server-kapcsolatkészletezés a Microsoft.Data.SqlClient használatával.
  • Az ASP.NET Core a CancellationToken paramétert a kéréshez köti. Ha megszakad a kliens kapcsolata, a token megszünteti a megnyitást, a parancsot és az olvasást.
  • Az @message és @id paraméterek megegyeznek az oszloptípusokkal és méretekkel. Az API ellenőrizi az üzenet hosszát, mielőtt elküldi az értéket az adatbázisba.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt visszaadja a beillesztett sort, beleértve a szerver által generált azonosítót és időbélyeget, második lekérdezés nélkül.
  • Más környezetekben az ASP.NET Core ugyanazt ConnectionStrings:Quickstart a kulcsot olvassa a környezeti változókból, például ConnectionStrings__Quickstart, vagy más konfigurációszolgáltatótól, például az Azure Key Vault-tól.

Troubleshoot

Hiba vagy tünet Mit kell ellenőrizni? További információ
Set the ConnectionStrings:Quickstart configuration value. Az alkalmazás nem találta meg a kapcsolati karakterlánc-et. Futtasd a projektmappában a dotnet user-secrets list parancsot, és ellenőrizd, hogy az alkalmazás fut-e a Development környezetben. A fejlesztés alatt álló alkalmazások titkos kulcsainak biztonságos tárolása ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' Induláskor A kapcsolati sztring Active Directory hitelesítési módot használ, de a projekt nem hivatkozik a Microsoft.Data.SqlClient.Extensions.Azure elemre. Add hozzá a csomagot a Microsoft.Data.SqlClient-val azonos verzióval. A Microsoft Entra hitelesítés 7.0-ban egy kiterjesztési csomagra vált
SqlException Induláskor Az alkalmazás nem tudott csatlakozni, vagy nem tudta létrehozni a táblát. A hibaszám azonosítja az okot, például sikertelen bejelentkezés esetén: 18456. Hibaelhárítás a konzol rövid útmutatóban
415 Unsupported Media Type A kérés nem állítja be a(z) Content-Type: application/json elemet. minimális API-k rövid útmutatója
Cannot bind parameter 'Headers' Futtattad a curl parancsot a Windows PowerShellben, ahol a(z) curl futtatja a(z) Invoke-WebRequest-t. Használd a PowerShell-parancsokat az API meghívása részben. Invoke-RestMethod
''' is an invalid start of a value A Bash curl parancsot futtattad a Parancssorban, amely az egyszeres idézőjeleket a kéréstörzs részeként küldi. Használd a Parancssor parancsait az API meghívása című részben. Az API meghívása

Erőforrások tisztítása

Töröld a táblát bármelyik lekérdezési eszközzel:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Távolítsd el a tárolt kapcsolati karakterlánc-t. A projekt mappájából futtasd:

dotnet user-secrets clear

Aztán töröld a projektmappát. Az anyamappából futtassa a következő parancsot a PowerShellben:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Bash esetén:

rm -rf SqlClientWebQuickstart

További lépések

  • Utolsó frissítés időpontja: