Rychlý start: Použijte Microsoft. Data.SqlClient v aplikaci ASP.NET Core

V tomto rychlém startu vytvoříte minimální API ASP.NET Core s Microsoft.Data.SqlClient 7.1.1.

Začínáte s prázdnou složkou, .NET SDK a databází SQL Server nebo Azure SQL, ke které máte přístup z počítače. Na závěr použijete webové API, které přidá zprávu do tabulky a přečte ji zpět podle ID.

Během cesty aplikace:

  • Čte svůj připojovací řetězec z konfigurace ASP.NET Core. Při lokálním vývoji hodnota pochází z uživatelských tajných údajů, takže zůstává mimo složku vašeho projektu.
  • Zaregistruje datovou třídu pomocí injektáže závislostí.
  • Otevírá a uvolňuje spojení pro každý požadavek, což umožňuje výchozímu poolu spojení znovu použít fyzická spojení.
  • Předává CancellationToken požadavku do každého volání databáze.

Aplikace používá stejnou dbo.SqlClientQuickstart tabulku jako Quickstart: Připojení a dotazování pomocí Microsoft.Data.SqlClient. Můžeš začít nejdřív kterýmkoli z nich.

Prerequisites

Současný ASP.NET Core běží na .NET, nikoli na .NET Frameworku. Pro použití ovladače z .NET Framework viz projekty .NET Framework.

Identita databáze potřebuje oprávnění k připojení, vytváření, vkládání a výběru z tabulky.

Vytvoření projektu

V prázdné složce spusťte tyto příkazy:

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 Přidá UserSecretsId do souboru projektu. ASP.NET Core načítá uživatelské tajné kódy pouze tehdy, když aplikace běží v prostředí Development, což je výchozí nastavení pro dotnet run.

Balíček rozšíření poskytuje autentizační režimy Microsoft Entra pro ovladač. Pokud vaše aplikace používá pouze SQL autentizaci, můžete vynechat Microsoft.Data.SqlClient.Extensions.Azure. Když používáte oba balíčky, nechte jejich verze stejné.

Konfigurujte spojení

Ukládejte připojovací řetězec jako ConnectionStrings:Quickstart v uživatelských tajemstvích. Uživatelská tajemství jsou uložena ve vašem uživatelském profilu, ne ve složce projektu, takže nejsou odesílána do správy zdrojového kódu. Nezadávejte heslo ani produkční připojovací řetězec do appsettings.json.

Vyberte jednu z těchto výchozích možností a nahraďte zástupné symboly. Příkazy dotnet user-secrets set používají jednoduché uvozovky pro PowerShell a Bash. V příkazovém řádku používejte místo toho dvojité uvozovky, protože příkazový řádek ukládá jednotlivé uvozovky jako součást klíče a hodnoty.

Azure SQL with Microsoft Entra ID

Přihlaste se s identitou Microsoft Entra, která má přístup k databázi. Pro lokální vývoj použijte vývojářský nástroj, jako je Azure CLI:

az login

Pak uložte připojovací řetězec. Zkopírujte přesný název serveru a databáze z databáze Azure SQL. Stejný připojovací řetězec funguje pro SQL databázi v Microsoft Fabric, když používáte názvy serveru a databáze z položky SQL databáze, jak je popsáno v rychlém startu konzole.

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

Tento připojovací řetězec neobsahuje žádný secret. služba Active Directory Default místně používá vaše přihlášení vývojáře. Při nasazení do Azure App Service nebo Azure Container Apps udělte spravované identitě aplikace přístup k databázi, změňte hodnotu na Authentication=služba Active Directory Managed Identity a nastavte ji v konfiguraci hostitele jako ConnectionStrings__Quickstart. Další možnosti najdete v článku Microsoft Entra authentication with Microsoft.Data.SqlClient.

Lokální SQL Server s SQL autentizací

Uložte připojovací řetězec pro lokální vývojovou instanci, která nemá důvěryhodný certifikát. Používejte jednoduché uvozovky, abyste zabránili PowerShellu a Bashu v interpretaci znaku $ v hesle.

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 přeskočí validaci serverového certifikátu. Používejte ho pouze s lokální vývojovou instancí. Pro sdílené nebo produkční instance SQL Server nainstalujte certifikát, kterému klient důvěřuje, a odstraňte TrustServerCertificate=true. Další informace naleznete v tématu Šifrování a ověření certifikátu v Microsoft.Data.SqlClient.

Přidání kódu

Nahraďte obsah Program.cs tímto kódem:

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;
    }
}

Spuštění aplikace

Spusťte aplikaci na pevném portu:

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

Při spuštění aplikace aplikace vytvoří tabulku, pokud neexistuje. Když je aplikace připravena, výstup obsahuje tyto řádky:

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

Pokud se aplikace nemůže připojit k databázi, při spuštění se zastaví a zobrazí se SqlException. Pro běžné příčiny viz Řešení problémů.

Zavolejte rozhraní API

Nechte aplikaci běžet a otevřete druhý terminál. Přidejte zprávu s požadavkem POST a pak ji přečtěte zpět podle ID pomocí požadavku GET. Pokud tabulka už má řádky, například z rychlého startu konzole, nahraďte v požadavku GET 1 hodnotou id, kterou vrátí váš požadavek POST.

Pro PowerShell:

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

PowerShell formátuje každou JSON odpověď jako tabulku. První řádek je odpovědí 201 Created na požadavek POST a druhý řádek je odpověď GET:

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

Windows PowerShell 5.1 zobrazuje createdAt jako řetězec, který API vrací. PowerShell 7 jej převádí na datum v lokálním čase, například 10/20/2026 7:04:43 PM.

V Windows PowerShell curl je alias pro Invoke-WebRequest, který nepřijímá možnosti curl. Použijte PowerShell příkazy nebo spusťte curl.exe z příkazového řádku.

Pro příkazový řádek:

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

Příkazový řádek nepovažuje jednoduché uvozovky za uvozovky, takže tělo JSON používá dvojité uvozovky uvozené zpětnými lomítky. Každý příkaz vytiskne odpověď JSON:

{"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"}

Pro příkazový řádek Bash:

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"}

Vaše ID a časová razítka se liší. Pokud jste spustili rychlý start na konzoli, ID pokračují z jejích řádků. Žádost o ID, které neexistuje, vrátí 404 Not Found. Prázdná zpráva vrátí 400 Bad Request.

Stiskněte Ctrl+C v prvním terminálu pro zastavení aplikace.

Jak kód funguje

  • Aplikace zaregistruje MessageStore jako singleton. Uchovává pouze připojovací řetězec, který načte z IConfiguration pouze jednou. Neudrží spojení.
  • Každá metoda vytvoří připojení SqlConnection, otevře ho, spustí jeden příkaz a odstraní ho s await using. Uvolnění vrací fyzické připojení do fondu připojení a další požadavek je znovu použije. Poolování připojení je zapnuté ve výchozím nastavení, takže ho nemusíte nastavovat. Pro možnosti ladění viz sdružování připojení SQL Serveru pomocí Microsoft.Data.SqlClient.
  • ASP.NET Core sváže parametr CancellationToken s požadavkem. Pokud se klient odpojí, token zruší operaci otevření, příkaz a čtení.
  • Parametry @id a @message odpovídají typům a velikostem sloupců. API ověřuje délku zprávy předtím, než odešle hodnotu do databáze.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt vrací vložený řádek, včetně ID a časového razítka generovaného serverem, bez druhého dotazu.
  • V jiných prostředích ASP.NET Core čte stejný ConnectionStrings:Quickstart klíč z proměnných prostředí, jako ConnectionStrings__Quickstartje , nebo z jiného poskytovatele konfigurace, například Azure Key Vault.

Troubleshoot

Chyba nebo příznak Co zkontrolovat Více informací
Set the ConnectionStrings:Quickstart configuration value. Aplikace nenašla připojovací řetězec. Spusťte dotnet user-secrets list ve složce projektu a zkontrolujte, že aplikace běží v prostředí Development. Bezpečné úložiště tajných kódů aplikací při vývoji ve ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' při spuštění připojovací řetězec používá režim ověřování služba Active Directory, ale projekt neodkazuje na Microsoft.Data.SqlClient.Extensions.Azure. Přidejte balíček se stejnou verzí jako Microsoft.Data.SqlClient. Autentizace Microsoft Entra přechází do balíčku rozšíření v 7.0
SqlException při spuštění Aplikace se nemohla připojit ani vytvořit tabulku. Chybové číslo určuje příčinu, například 18456 pro neúspěšné přihlášení. Řešte problémy v rychlém startu konzole
415 Unsupported Media Type Požadavek nenastavuje Content-Type: application/json. Stručný přehled minimálních rozhraní API
Cannot bind parameter 'Headers' Spustil jsi příkaz curl ve Windows PowerShellu, kde se pomocí curl spouští Invoke-WebRequest. Použijte příkazy PowerShellu v části Volání rozhraní API. Invoke-RestMethod
''' is an invalid start of a value Příkaz Bash curl jste spustil v příkazovém řádku, který posílá jednoduché uvozovky jako součást těla. Použijte příkazy v příkazovém řádku v části Volání rozhraní API. Volání rozhraní API

Vyčistěte zdroje

Smažte tabulku s jakýmkoli dotazovacím nástrojem:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Odstraňte uložený připojovací řetězec. Ze složky projektu spusťte:

dotnet user-secrets clear

Pak smažte složku projektu. Z nadřazené složky spusťte následující příkaz v PowerShellu:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Pro příkazový řádek Bash:

rm -rf SqlClientWebQuickstart

Další kroky

  • Poslední aktualizace v