Gyorsindítás: Csatlakozás és lekérdezés a Microsoft.Data.SqlClient használatával

Ebben a rövid útmutatóban egy .NET-konzolalkalmazást hozol létre 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égére lesz egy konzolos alkalmazásod, ami létrehoz egy táblázatot, két sort helyez be paraméterekkel, és visszaolvassa azokat.

Útközben az alkalmazás:

A kapcsolati karakterláncet a forráskód helyett egy környezeti változóból olvassa ki.
Aszinkron módon nyit meg egy kapcsolatot.
Minden, az adatbázisba küldött értékhez paramétereket használ.
SQL hibákat és megszakítást kezel.

Ugyanezen adathozzáférés webes API-ba való beépítéséről lásd: Gyorsútmutató: A Microsoft.Data.SqlClient használata ASP.NET Core-alkalmazásban. Ugyanazt a táblázatot használja.

Prerequisites

A .NET 10 SDK vagy egy újabb támogatott .NET SDK. Az SDK Windows-on, Linuxon és macOS-en fut. Az SDK a .NET Framework verziót is készíti a mintaverzióból, amely csak Windows-on fut, és .NET Framework 4.8.1-et igényel. Új fejlesztéshez használd a .NET verziót.
Egy kódszerkesztő. Használhatod a Visual Studio-t, a Visual Studio Code-ot vagy bármely szerkesztőt a .NET CLI-vel együtt. Ez a cikk a .NET CLI-t használja.
Egy adatbázis, amihez csatlakozni tudsz. Ha nincs ilyened, hozz létre egyet az alábbi opciókkal.

SQL-adatbázis létrehozása

Létrehozni vagy csatlakozni SQL adatbázishoz az alábbi platformok egyikén:

SQL-adatbázis létrehozása percek alatt az Azure Portal használatával

Adatbázis-engedélyek

Az alkalmazás saját táblázatot hoz létre, így nincs szükség mintaadatokra. 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.

Az SQL adatbázishoz a Microsoft Fabric-ben másold le a szerver- és adatbázisneveket az SQL adatbázis elemből. Ne használd az SQL analitikai végpontot. Az identitáshoz Olvasási elem engedélyre van szükség, amit egy munkaterületi szerep vagy elem jogosultság biztosíthat. További információért lásd: Hitelesítés az SQL adatbázisban. Az SQL hitelesítés nem támogatott.

Azure SQL Database esetén konfiguráld a Microsoft Entra ID hitelesítést és adatbázis-hozzáférést.

Egy üres mappában futtassa ezeket a parancsokat:

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

A konzol sablon nem kínál .NET Framework célokat. Egy üres mappában hozd létre a projektet:

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

Cseréld le a(z) SqlClientQuickstart.csproj tartalmát ezzel a projektfájllal:

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

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

</Project>

Ezután adjuk hozzá a csomagokat:

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

A kiterjesztési csomag biztosítja a meghajtó Microsoft Entra hitelesítési módjait, például Active Directory Default. Ha az alkalmazásod csak SQL hitelesítést vagy Windows integrált hitelesítést használ, akkor kihagyhatod Microsoft.Data.SqlClient.Extensions.Azure. Ha mindkét csomagot használod, ügyelj arra, hogy a verziójuk azonos legyen. További telepítési lehetőségekért lásd: Telepítés, frissítés és üzembe helyezés Microsoft.Data.SqlClient.

Konfiguráld a kapcsolatot

Állítsd be a SQL_CONNECTION_STRING környezeti változót az adatbázisodhoz. Ne helyezz jelszót, hozzáférési tokent vagy éles kapcsolati karakterláncot a forráskódba.

Válassz ki ezek közül az egyik kezdőpontot, és cseréld le a helykitöltőket.

Azure SQL vagy Fabricbeli SQL-adatbázis Microsoft Entra ID-val

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

Másold le a pontos szerver- és adatbázisneveket az Azure SQL adatbázisból vagy az SQL adatbázis elemből a Fabric-ben. PowerShell esetén:

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

Bash esetén:

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

Egy Azure-ban üzemeltetett alkalmazás esetén adj adatbázis-hozzáférést a felügyelt identitásának, majd használd Authentication=Active Directory Managed Identity. További lehetőségekért lásd: Microsoft Entra-hitelesítés a Microsoft.Data.SqlClienttel.

SQL Server SQL hitelesítéssel

Használd a szervert, portot, adatbázist és bejelentkezési nevet az SQL Server példányodhoz. A következő példa egy helyi fejlesztési példányra vonatkozik, amelynek nincs megbízható tanúsítványa. PowerShell esetén:

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

Bash esetén:

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 kihagyja a szerver tanúsítvány ellenőrzését. Csak olyan helyi fejlesztési instansszal használd, amelynek nincs megbízható tanúsítványa. Megosztott vagy éles SQL Server-példányok esetén telepítsen egy olyan tanúsítványt, amelyben az ügyfél megbízik, használja a tanúsítványon szereplő kiszolgálónevet, és távolítsa el a(z) TrustServerCertificate=true elemet. További információ: Titkosítás és tanúsítványérvényesítés a Microsoft.Data.SqlClientben.

Ha a környezeted támogatja a Windows integrált hitelesítést vagy a Kerberost, cseréld le a(z) User ID és Password elemeket erre: Integrated Security=true. A beállítási követelményekért lásd: SQL Server és Windows-hitelesítés.

A kód hozzáadása

.NET
.NET-keretrendszer

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

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

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

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

Az alkalmazás futtatása

Futtassa az alkalmazást:

dotnet run

Amikor először futtatod az alkalmazást, a tábla üres, és a kimenet így néz ki:

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)

Az időbélyegeid eltérnek. Minden későbbi futás két újabb sort ad hozzá, így az azonosítók az előző futástól folytatódnak.

Ha az alkalmazás nem tud csatlakozni, kinyomtatja az SQL hibaszámot, a kliens kapcsolati azonosítóját, a hibaüzenetet és a belső kivétel üzenetet, majd 3-as kóddal kilép. Gyakori hibák esetén lásd: Hibakeresés.

A kód működése

OpenAsync, ExecuteNonQueryAsync, ExecuteScalarAsync, ExecuteReaderAsync, , és ReadAsync mind ugyanazt CancellationTokenkapják. Nyomja meg a Ctrl+C gombot, hogy megszakítsa a folyamatban lévő műveletet.
A beszúrási parancs egyszer jön létre, és üzenetenként egyszer fut le. Csak a paraméterérték változik.
A paramétertípusok és méretek megegyeznek a táblázatoszlopokkal. A paraméterek az SQL-szövegtől elkülönítve küldik az értékeket, ami megakadályozza, hogy ezek az értékek megváltoztassák a parancsot, és segít az SQL Server-nek a lekérdezési tervek újrahasznosításában.
OUTPUT INSERTED.Id visszaadja az új identitásértéket, így ExecuteScalarAsync az azonosítót második lekérdezés nélkül adja vissza.
await using felszabadítja a parancsokat, az olvasót és a kapcsolatot, még akkor is, ha kivétel adódik. A kapcsolat lezárása visszaadja a kapcsolatpoolba. A .NET Framework verzió using blokkokat használ, mert ezek a típusok nem implementálják a IAsyncDisposable elemet a .NET Frameworkön.
SqlException.Number azonosítja a hibát, és ClientConnectionId lehetővé teszi, hogy egy klienshibát a szerveroldali naplókhoz társítson. Linux és macOS rendszerben fellépő kapcsolódási hibák esetén az ok gyakran csak a(z) InnerException részben látható, például egy tanúsítvány-ellenőrzési hiba az általános error: 35 - An internal exception was caught mögött.

Troubleshoot

Hiba vagy tünet	Mit kell ellenőrizni?	További információ
`The certificate chain was issued by an authority that is not trusted`Windows-on. Linuxon és macOS rendszeren `error: 35 - An internal exception was caught`, majd a belső kivétel `Certificate failed chain validation` következik ezzel: `UntrustedRoot`.	Az ügyfél nem bízik meg a szerver tanúsítványában, vagy a kapcsolati karakterláncban szereplő szervernév nem egyezik meg a tanúsítvánnyal. Telepíts egy megbízható tanúsítványt. A `TrustServerCertificate=true` elemet csak helyi fejlesztői példánnyal használd.	Titkosítás és tanúsítvány ellenőrzése a Microsoft-ban. Data.SqlClient
`SQL error 18456` és `Login failed for user`	A felhasználónév, jelszó vagy adatbázisnév hibás, vagy a felhasználó nem fér hozzá az adatbázishoz. Microsoft Entra ID esetén ellenőrizd, hogy az identitás adatbázis-felhasználóként lett-e hozzáadva.	Az SqlClient hibaelhárítási útmutatója
`A network-related or instance-specific error occurred` a(z) `error: 26`, `error: 40` vagy `The wait operation timed out` használatával. Linuxon és macOS-en időtúllépés esetén `SQL error 258` jelenik meg `error: 35` kíséretében, majd a belső kivétel: `The connection attempt timed out`.	A szerver neve vagy portja hibás, a szerver nem fogad el távoli TCP kapcsolatokat, vagy egy tűzfal blokkolja a portot. Azure SQL esetén ellenőrizze a kiszolgáló tűzfalszabályait.	Az SqlClient hibaelhárítási útmutatója
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	A kapcsolati karakterlánc `Active Directory` hitelesítési módot használ, de a projekt nem hivatkozik a(z) `Microsoft.Data.SqlClient.Extensions.Azure` elemre. Add a csomagot a(z) `Microsoft.Data.SqlClient` csomagéval azonos verzióval.	A Microsoft Entra hitelesítés 7.0-ban egy bővítménycsomagba kerül
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	A projekt nem utal a `Microsoft.Data.SqlClient` csomagra. Futtasd a `dotnet add package` parancsot abból a mappából, amely a projektfájlt tartalmazza.	Telepítsd, frissítsd és telepítsd a Microsoft-ot. Data.SqlClient
Jelentések visszaállítása `NU1902` vagy `NU1903` egy tranzitív csomaghoz	Közzétettek egy figyelmeztetést egy csomagról, amelytől az illesztőprogram függ.	Műveletek ismert sebezhetőségeket tartalmazó csomagok jelentésekor

Erőforrások tisztítása

A tábla az adatbázisban marad, miután az alkalmazás kilép. Ha nem tervezed folytatni az ASP.NET Core gyorsindítást, amely ugyanazt a táblát használja, töröld bármelyik lekérdezési eszközzel:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Aztán töröld a projektmappát. Az anyamappából, PowerShell esetén:

Remove-Item -Recurse -Force SqlClientQuickstart

Bash esetén:

rm -rf SqlClientQuickstart

Töröld a környezeti változót, hogy a kapcsolati karakterlánc ne maradjon a shell sessionben. PowerShellhez futtatd Remove-Item Env:\SQL_CONNECTION_STRING. A Bashben futtasd: unset SQL_CONNECTION_STRING.

Használd a mintát egy alkalmazásban

Tartsd meg ezeket a határokat, amikor a mintát API-ba, szolgáltatásba, asztali alkalmazásba vagy háttérfolyamatba helyezed:

Töltsd be a kapcsolati információkat az alkalmazás konfigurációs rendszerén keresztül.
Nyiss meg egy kapcsolatot egy rövid munkafolyamathoz, majd szüntesd meg.
Add át a CancellationToken elemet az open-, command- és readerhívásoknak.
Állítsd be a parancsidőkorlátokat a művelet alapján.
Használj paramétereket minden olyan értékhez, amely az SQL utasításon kívül érkezik.
Naplózza SqlException.Number és ClientConnectionId elemeket hitelesítő adatok vagy hozzáférési tokenek naplózása nélkül.
Csak átmeneti hibák esetén és csak akkor adj ismétlést, ha a művelet megismétlése biztonságos.

Következő lépések

Visszajelzés

Hasznosnak találta ezt az oldalt?

Utolsó frissítés időpontja: 2026-10-23

Gyorsindítás: Csatlakozás és lekérdezés a Microsoft.Data.SqlClient használatával

Prerequisites

SQL-adatbázis létrehozása

Adatbázis-engedélyek

A projekt létrehozása

Konfiguráld a kapcsolatot

Azure SQL vagy Fabricbeli SQL-adatbázis Microsoft Entra ID-val

SQL Server SQL hitelesítéssel

A kód hozzáadása

Az alkalmazás futtatása

A kód működése

Troubleshoot

Erőforrások tisztítása

Használd a mintát egy alkalmazásban

Következő lépések

Visszajelzés

További források