A Microsoft.Data.SqlClient használata .NET-alkalmazásban

Ebben a gyorsindításban létrehozol egy .NET konzolalkalmazást, amely:

A forráskód helyett a környezetből olvassa a kapcsolati karakterláncot.
Aszinkron módon nyit meg egy kapcsolatot.
Létrehoz egy táblázatot, ha nem létezik.
Hozzáad egy sort, amelyben paraméterezett parancs található.
Paraméterezett lekérdezéssel ellátott sorokat olvas.
Kezeli az SQL és törlési hibákat.

A példa a Microsoft. Data.SqlClient 7.0.3-at használja, a jelenlegi stabil kiadást.

Prerequisites

Szükséged van a .NET 10 SDK-ra vagy egy későbbi támogatott .NET SDK-ra.

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

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

A projekt létrehozása

Futtassa a következő parancsokat:

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

A bővítménycsomag az illesztőprogram által biztosított Microsoft Entra ID-hitelesítési módokat kínál. Egy olyan alkalmazás, amely csak Windows integrált hitelesítést vagy SQL hitelesítést használ, kihagyhatja Microsoft.Data.SqlClient.Extensions.Azurea .

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.

Fabric SQL vagy Azure SQL jelszó nélküli hitelesítéssel

Jelentkezz be egy Microsoft Entra ID-ben lévő 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 SQL adatbázis elemből a Fabric-ben vagy az Azure SQL adatbázisból. 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, Azure SQL-hez csatlakozó alkalmazás esetén adj adatbázis-hozzáférést a felügyelt identitásának, majd használd a Authentication=Active Directory Managed Identity elemet. További Microsoft Entra ID opciókért lásd: Microsoft Entra ID hitelesítés.

SQL Server TCP-n keresztül

Használd a szervert, portot, adatbázist és bejelentkezést a meglévő SQL Server-edből, vagy a beállító útmutatóból, amit követtél. Az alábbi SQL hitelesítési példa egy helyi fejlesztő konténerre vonatkozik. 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.

Ha a környezet támogatja a Windows integrált hitelesítést vagy a Kerberost, cserélje 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 hitelesítés.

Az alkalmazáskód hozzáadása

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

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

    int insertedId;
    using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        insertCommand.Parameters.Add(
            new SqlParameter("@message", SqlDbType.NVarChar, 200)
            {
                Value = "Hello from Microsoft.Data.SqlClient"
            });

        object? result =
            await insertCommand.ExecuteScalarAsync(cancellation.Token);
        insertedId = Convert.ToInt32(result);
    }

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

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

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

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

    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);
    return 3;
}

A paramétertípusok és méretek megegyeznek a táblázatoszlopokkal. A paraméterek külön küldenek értékeket az SQL szövegtől, ami megakadályozza, hogy ezek az értékek módosítsák a parancsszintaxist, és segít az SQL Server lekérdezési tervek újrahasznosításában.

await using akkor is felszabadítja az olvasóobjektumot és a kapcsolatot, ha kivétel következik be. A kapcsolat lezárása visszaadja annak fizikai kapcsolatát a kapcsolatpoolba, ahelyett, hogy az alkalmazás teljes élettartama alatt egy kapcsolatot tartana nyitva.

Az alkalmazás futtatása

Futtassa az alkalmazást:

dotnet run

Az alkalmazás kinyomtatja azt a sort, amelyet beillesztett:

1: Hello from Microsoft.Data.SqlClient at <timestamp>

Az identitásérték és az időbélyeg minden adatbázisban eltérő.

Ha a kapcsolat meghibásodik, használd az SQL hibaszámot és a kliens kapcsolati azonosítót a hibakimenetből. Ellenőrizd a szerver- és adatbázisneveket, a hálózati hozzáférést, az adatbázis-jogosultságokat, hitelesítési beállítást és a tanúsítvány konfigurációját. Ne add hozzá a TrustServerCertificate=true elemet egy Azure SQL- vagy éles kapcsolathoz általános kapcsolatjavításként.

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érfeldolgozóba helyezed:

A kapcsolati információk betöltése 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?

Last updated on 2026-09-21