Rychlý začátek: Připojení a dotazování pomocí Microsoft.Data.SqlClient

V tomto rychlém startu vytvoříte .NET konzolovou aplikaci 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. Výsledkem je konzolová aplikace, která vytvoří tabulku, vloží dva řádky s parametry a přečte je zpět.

Přitom aplikace:

Čte svůj připojovací řetězec z proměnné prostředí místo zdrojového kódu.
Otevírá spojení asynchronně.
Používá parametry pro každou hodnotu, kterou pošle do databáze.
Řeší chyby SQL a zrušení operace.

Pro začlenění stejného přístupu k datům do webového API viz Quickstart: Use Microsoft.Data.SqlClient v aplikaci ASP.NET Core. Používá stejnou tabulku.

Předpoklady

.NET 10 SDK nebo novější podporované .NET SDK. SDK běží na Windows, Linuxu a macOS. SDK také vytváří verzi ukázky pro .NET Framework, která běží pouze ve Windows a vyžaduje .NET Framework 4.8.1. Pro nový vývoj použijte .NET verzi.
Editor kódu. Můžete používat Visual Studio, Visual Studio Code nebo jakýkoli editor společně s .NET CLI. Tento článek používá .NET CLI.
Databáze, ke které se můžete připojit. Pokud ji nemáte, vytvořte si ji pomocí následujících možností.

Vytvoření databáze SQL

Vytvořte nebo se připojte k SQL databázi na jedné z následujících platforem:

Vytvoření databáze SQL v řádu minut pomocí webu Azure Portal

Oprávnění k databázi

Aplikace vytváří vlastní tabulku, takže nepotřebujete vzorková data. Identita databáze potřebuje oprávnění k připojení, vytváření, vkládání a výběru z tabulky.

Pro SQL databázi v Microsoft Fabric zkopírujte názvy serverů a databází z položky SQL databáze. Nepoužívej SQL analytics endpoint. Identita potřebuje oprávnění ke čtení položky, které může poskytnout role pracovního prostoru nebo oprávnění k položce. Pro více informací viz Autentizace v SQL databázi. SQL autentizace není podporována.

Pro Azure SQL Database nakonfigurujte Microsoft Entra ID autentizaci a přístup k databázi.

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

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

Šablona konzole nenabízí cíle pro .NET Framework. V prázdné složce vytvořte projekt:

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart

Nahraďte obsah SqlClientQuickstart.csproj tímto projektovým souborem:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net481</TargetFramework>
  </PropertyGroup>

</Project>

Pak přidejte balíčky:

dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

Balíček rozšíření poskytuje autentizační režimy ovladače Microsoft Entra, například služba Active Directory Default. Pokud vaše aplikace používá pouze SQL autentizaci nebo integrovanou autentizaci Windows, můžete vynechat Microsoft.Data.SqlClient.Extensions.Azure. Když používáte oba balíčky, nechte jejich verze stejné. Pro další možnosti instalace viz Instalace, aktualizace a nasazení Microsoft.Data.SqlClient.

Konfigurujte spojení

Nastavte pro svou databázi SQL_CONNECTION_STRING proměnnou prostředí. Do zdrojového kódu nevkládejte heslo, přístupový token ani připojovací řetězec pro produkční prostředí.

Vyberte jednu z těchto výchozích možností a nahraďte zástupné symboly.

Azure SQL or SQL database in Fabric 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

Zkopírujte přesný název serveru a databáze z databáze Azure SQL nebo z položky databáze SQL ve Fabric. Pro PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Pro příkazový řádek Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Pro aplikaci hostovanou v Azure udělte její spravované identitě přístup k databázi a poté použijte Authentication=služba Active Directory Managed Identity. Další možnosti najdete v článku Microsoft Entra authentication with Microsoft. Data.SqlClient.

SQL Server s ověřením SQL

Použijte server, port, databázi a přihlašovací jméno pro instanci SQL Server. Následující příklad je pro lokální vývojovou instanci, která nemá důvěryhodný certifikát. Pro PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;User ID=<user-id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Pro příkazový řádek Bash:

export SQL_CONNECTION_STRING='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í, která nemá důvěryhodný certifikát. Pro sdílené nebo produkční instance SQL Server nainstalujte certifikát, kterému klient důvěřuje, použijte název serveru na tomto certifikátu a odstraňte TrustServerCertificate=true. Další informace naleznete v tématu Šifrování a ověření certifikátu v Microsoft.Data.SqlClient.

Pokud vaše prostředí podporuje integrované ověřování systému Windows nebo Kerberos, nahraďte User ID a Password za Integrated Security=true. Požadavky na nastavení najdete v části SQL Server a ověřování systému Windows.

Přidání kódu

.NET
.NET Framework

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

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

string? connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING");

if (string.IsNullOrWhiteSpace(connectionString))
{
    Console.Error.WriteLine(
        "Set the SQL_CONNECTION_STRING environment variable.");
    return 1;
}

using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, eventArgs) =>
{
    eventArgs.Cancel = true;
    cancellation.Cancel();
};

try
{
    await using var connection = new SqlConnection(connectionString);
    await connection.OpenAsync(cancellation.Token);

    const string createTableSql = """
        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 createCommand =
        new SqlCommand(createTableSql, connection) { CommandTimeout = 30 })
    {
        await createCommand.ExecuteNonQueryAsync(cancellation.Token);
    }

    const string insertSql = """
        INSERT INTO dbo.SqlClientQuickstart (Message)
        OUTPUT INSERTED.Id
        VALUES (@message);
        """;

    string[] messages =
    [
        "Hello from Microsoft.Data.SqlClient",
        "Parameters keep values out of the SQL text"
    ];

    int firstId = 0;
    await using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        SqlParameter messageParameter =
            insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

        foreach (string message in messages)
        {
            messageParameter.Value = message;
            int id = (int)(await insertCommand.ExecuteScalarAsync(
                cancellation.Token))!;
            Console.WriteLine($"Inserted row {id}.");
            firstId = firstId == 0 ? id : firstId;
        }
    }

    const string querySql = """
        SELECT Id, Message, CreatedAt
        FROM dbo.SqlClientQuickstart
        WHERE Id >= @firstId
        ORDER BY Id;
        """;

    await using var queryCommand =
        new SqlCommand(querySql, connection) { CommandTimeout = 30 };
    queryCommand.Parameters.Add("@firstId", SqlDbType.Int).Value = firstId;

    await using SqlDataReader reader =
        await queryCommand.ExecuteReaderAsync(cancellation.Token);

    while (await reader.ReadAsync(cancellation.Token))
    {
        Console.WriteLine(
            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
            $"(created {reader.GetDateTimeOffset(2):u})");
    }

    return 0;
}
catch (OperationCanceledException)
{
    Console.Error.WriteLine("The operation was canceled.");
    return 2;
}
catch (SqlException ex)
{
    Console.Error.WriteLine(
        $"SQL error {ex.Number}, connection {ex.ClientConnectionId}: " +
        ex.Message);
    if (ex.InnerException is not null)
    {
        Console.Error.WriteLine(ex.InnerException.Message);
    }
    return 3;
}

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

using System;
using System.Data;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task<int> Main()
    {
        string connectionString =
            Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING");

        if (string.IsNullOrWhiteSpace(connectionString))
        {
            Console.Error.WriteLine(
                "Set the SQL_CONNECTION_STRING environment variable.");
            return 1;
        }

        using (var cancellation = new CancellationTokenSource())
        {
            Console.CancelKeyPress += (sender, eventArgs) =>
            {
                eventArgs.Cancel = true;
                cancellation.Cancel();
            };

            try
            {
                await RunAsync(connectionString, cancellation.Token);
                return 0;
            }
            catch (OperationCanceledException)
            {
                Console.Error.WriteLine("The operation was canceled.");
                return 2;
            }
            catch (SqlException ex)
            {
                Console.Error.WriteLine(
                    $"SQL error {ex.Number}, connection {ex.ClientConnectionId}: " +
                    ex.Message);
                if (ex.InnerException != null)
                {
                    Console.Error.WriteLine(ex.InnerException.Message);
                }
                return 3;
            }
        }
    }

    static async Task RunAsync(string connectionString, CancellationToken token)
    {
        using (var connection = new SqlConnection(connectionString))
        {
            await connection.OpenAsync(token);

            const string createTableSql = @"
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;";

            using (var createCommand =
                new SqlCommand(createTableSql, connection) { CommandTimeout = 30 })
            {
                await createCommand.ExecuteNonQueryAsync(token);
            }

            const string insertSql = @"
INSERT INTO dbo.SqlClientQuickstart (Message)
OUTPUT INSERTED.Id
VALUES (@message);";

            string[] messages =
            {
                "Hello from Microsoft.Data.SqlClient",
                "Parameters keep values out of the SQL text"
            };

            int firstId = 0;
            using (var insertCommand =
                new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
            {
                SqlParameter messageParameter =
                    insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

                foreach (string message in messages)
                {
                    messageParameter.Value = message;
                    int id = (int)await insertCommand.ExecuteScalarAsync(token);
                    Console.WriteLine($"Inserted row {id}.");
                    firstId = firstId == 0 ? id : firstId;
                }
            }

            const string querySql = @"
SELECT Id, Message, CreatedAt
FROM dbo.SqlClientQuickstart
WHERE Id >= @firstId
ORDER BY Id;";

            using (var queryCommand =
                new SqlCommand(querySql, connection) { CommandTimeout = 30 })
            {
                queryCommand.Parameters.Add("@firstId", SqlDbType.Int).Value = firstId;

                using (SqlDataReader reader =
                    await queryCommand.ExecuteReaderAsync(token))
                {
                    while (await reader.ReadAsync(token))
                    {
                        Console.WriteLine(
                            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
                            $"(created {reader.GetDateTimeOffset(2):u})");
                    }
                }
            }
        }
    }
}

Spuštění aplikace

Spuštění aplikace:

dotnet run

Poprvé, když aplikaci spustíte, je tabulka prázdná a výstup vypadá takto:

Inserted row 1.
Inserted row 2.
1: Hello from Microsoft.Data.SqlClient (created 2026-10-20 20:56:10Z)
2: Parameters keep values out of the SQL text (created 2026-10-20 20:56:10Z)

Vaše časová razítka se liší. Každý další běh přidává další dva řádky, takže ID pokračují od posledního běhu.

Pokud se aplikace nemůže připojit, vytiskne SQL chybové číslo, ID připojení klienta, chybovou zprávu a zprávu vnitřní výjimky a poté se ukončí s kódem 3. Pro běžné chyby viz Řešení problémů.

Jak kód funguje

OpenAsync, ExecuteNonQueryAsync, ExecuteReaderAsync, ReadAsync a CancellationToken všechny dostávají stejné ExecuteScalarAsync. Stiskněte Ctrl+C pro zrušení probíhající operace.
Příkaz insert se vytvoří jednou a spustí se jednou pro každou zprávu. Mění se pouze hodnota parametru.
Typy parametrů a velikosti odpovídají sloupcům tabulky. Parametry posílají hodnoty odděleně od SQL textu, což brání tomu, aby tyto hodnoty změnily příkaz, a pomáhá SQL Serveru znovu použít plány dotazů.
OUTPUT INSERTED.Id vrátí novou hodnotu identity, takže ExecuteScalarAsync vrátí ID bez druhého dotazu.
await using uvolní příkazy, čtečku a připojení, i když nastane výjimka. Po uvolnění se připojení vrátí do fondu připojení. Verze .NET Frameworku používá bloky using, protože tyto typy neimplementují IAsyncDisposable v .NET Frameworku.
SqlException.Number identifikuje chybu a ClientConnectionId vám umožní spárovat selhání klienta se serverovými logy. U selhání spojení na Linuxu a macOS je příčina často pouze v InnerException, například selhání ověření certifikátu za generickým error: 35 - An internal exception was caught.

Troubleshoot

Chyba nebo příznak	Co zkontrolovat	Více informací
`The certificate chain was issued by an authority that is not trusted`na Windows. V Linuxu a macOS `error: 35 - An internal exception was caught`, za níž následuje vnitřní výjimka `Certificate failed chain validation` s `UntrustedRoot`.	Klient nevěří serverovému certifikátu, nebo název serveru v připojovací řetězec neodpovídá certifikátu. Nainstalujte důvěryhodný certifikát. Používejte `TrustServerCertificate=true` pouze s lokální vývojovou instancí.	Šifrování a ověřování certifikátů v Microsoftu. Data.SqlClient
`SQL error 18456` s `Login failed for user`	Uživatelské jméno, heslo nebo název databáze jsou nesprávné, nebo uživatel nemá přístup k databázi. Pro Microsoft Entra ID zkontrolujte, že identita byla přidána jako uživatel databáze.	Průvodce odstraňováním potíží s SqlClient
`A network-related or instance-specific error occurred` s `error: 26`, `error: 40`, nebo `The wait operation timed out`. V Linuxu a macOS se při vypršení časového limitu zobrazí `SQL error 258` s `error: 35`, následované vnitřní výjimkou `The connection attempt timed out`.	Název serveru nebo port je špatný, server nepřijímá vzdálená TCP připojení, nebo firewall blokuje port. Pro Azure SQL zkontrolujte pravidla serverového firewallu.	Průvodce odstraňováním potíží s SqlClient
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	Connection string používá autentizační režim `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
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	Projekt neodkazuje na balíček `Microsoft.Data.SqlClient`. Spusť `dotnet add package` příkaz ze složky, která obsahuje projektový soubor.	Nainstalujte, aktualizujte a nasazujte Microsoft. Data.SqlClient
Obnovit reporty `NU1902` nebo `NU1903` pro závislý balíček	Balík, na kterém řidič spoléhá, má zveřejněné upozornění.	Akce, když jsou hlášeny balíčky s známými zranitelnostmi

Vyčistěte zdroje

Tabulka zůstává ve vaší databázi i po ukončení aplikace. Pokud neplánujete pokračovat s rychlým startem ASP.NET Core, který používá stejnou tabulku, odstraňte ji pomocí libovolného dotazovacího nástroje:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Pak smažte složku projektu. Z nadřazené složky v PowerShellu:

Remove-Item -Recurse -Force SqlClientQuickstart

Pro příkazový řádek Bash:

rm -rf SqlClientQuickstart

Vymažte proměnnou prostředí, aby připojovací řetězec nezůstal ve vaší shell relaci. Pro PowerShell použijte Remove-Item Env:\SQL_CONNECTION_STRING. V Bash spusťte unset SQL_CONNECTION_STRING.

Použijte vzor v aplikaci

Tyto hranice si zachovejte při přesunu ukázky do API, služby, desktopové aplikace nebo úlohy na pozadí:

Načtěte informace o připojení přes konfigurační systém aplikace.
Otevřete jedno připojení pro krátkou jednotku práce a pak ho zrušte.
Předejte průchodné CancellationToken otevřené, příkazové a čtecí volání.
Nastavte časové limity příkazů podle daného postupu.
Používejte parametry pro každou hodnotu, která pochází mimo SQL příkaz.
Logujte SqlException.Number a ClientConnectionId bez logovacích přihlašovacích údajů nebo přístupových tokenů.
Opakování pokusů přidávejte pouze při přechodných selháních a pouze tehdy, když je bezpečné operaci opakovat.

Další kroky

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-10-23

Rychlý začátek: Připojení a dotazování pomocí Microsoft.Data.SqlClient

Předpoklady

Vytvoření databáze SQL

Oprávnění k databázi

Vytvoření projektu

Konfigurujte spojení

Azure SQL or SQL database in Fabric with Microsoft Entra ID

SQL Server s ověřením SQL

Přidání kódu

Spuštění aplikace

Jak kód funguje

Troubleshoot

Vyčistěte zdroje

Použijte vzor v aplikaci

Další kroky

Váš názor

Další materiály