Použijte Microsoft. Data.SqlClient v .NET aplikaci

V tomto rychlém startu vytvoříte .NET konzolovou aplikaci, která:

  • Čte svůj připojovací řetězec z prostředí namísto ze zdrojového kódu.
  • Otevírá spojení asynchronně.
  • Vytvoří tabulku, pokud neexistuje.
  • Vloží řádek s parametrizovaným příkazem.
  • Čte řádky pomocí parametrizovaného dotazu.
  • Řeší SQL a chyby při rušení.

Příklad používá Microsoft. Data.SqlClient 7.0.3, aktuální stabilní verze.

Předpoklady

Potřebujete sadu .NET 10 SDK nebo novější podporovanou sadu .NET SDK.

Vytvoření databáze SQL

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

Quickstart vytváří vlastní tabulku, takže vzorová data nejsou potřeba. 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.

Vytvoření projektu

Spusťte tyto příkazy:

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

Balíček rozšíření poskytuje autentizační režimy Microsoft Entra ID poskytované ovladačem. Aplikace, která používá pouze integrovanou autentizaci Windows nebo SQL autentizaci, může vynechat Microsoft.Data.SqlClient.Extensions.Azure.

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.

Fabric SQL nebo Azure SQL s autentizací bez hesla

Přihlaste se s identitou v Microsoft Entra ID, 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ázvy serverů a databází z položky SQL databáze ve Fabric nebo Azure SQL databázi. 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, která se připojuje k Azure SQL, udělte její spravované identitě přístup k databázi a poté použijte Authentication=služba Active Directory Managed Identity. Pro další možnosti Microsoft Entra ID viz Microsoft Entra ID autentizace.

SQL Server přes TCP

Použijte server, port, databázi a přihlašovací údaje ze svého stávajícího serveru SQL Server nebo z návodu k nastavení, podle kterého jste postupovali. Následující příklad SQL autentizace je pro lokální vývojový kontejner. 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.

Pokud prostředí podporuje integrovanou autentizaci Windows nebo Kerberos, nahraďte User ID a Password .Integrated Security=true Pro požadavky na nastavení viz SQL Server autentizace.

Přidání kódu aplikace

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

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

Typy parametrů a velikosti odpovídají sloupcům tabulky. Parametry posílají hodnoty odděleně od SQL textu, což zabraňuje změně syntaxe příkazů a pomáhá SQL Server znovu používat plány dotazů.

await using uvolní čtečku i připojení i v případě, že dojde k výjimce. Vyřazení spojení vrací jeho fyzické spojení do poolu místo toho, aby jedno spojení zůstalo otevřené po celou dobu trvání aplikace.

Spuštění aplikace

Spusťte aplikaci:

dotnet run

Aplikace vytiskne řádek, který vložila:

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

Hodnota identity a časové razítko se liší v každé databázi.

Pokud spojení selže, použijte SQL chybové číslo a ID klientského připojení z chybového výstupu. Zkontrolujte názvy serverů a databází, přístup do sítě, oprávnění k databázi, nastavení autentizace a konfiguraci certifikátů. Nepřidávejte TrustServerCertificate=true k Azure SQL ani k připojení k produkčnímu prostředí jako obecné řešení problémů s připojením.

Použijte vzor v aplikaci

Tyto hranice si zachovejte při přesunu vzorku do API, služby, desktopové aplikace nebo pracovníka na pozadí:

  • Načtěte informace o připojení prostřednictvím konfiguračního systému 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

  • Last updated on