Snabbstart: Ansluta och köra frågor med Microsoft.Data.SqlClient

I denna snabbstart bygger du en .NET-konsolapp med Microsoft.Data.SqlClient 7.1.1.

Du börjar med en tom mapp, .NET SDK och en SQL Server- eller Azure SQL-databas som du kan nå från din dator. Du avslutar med en konsolapp som skapar en tabell, lägger in två rader med parametrar och läser tillbaka dem.

Under tiden har appen:

Läser sin reťazec pripojenia från en miljövariabel istället för källkod.
Öppnar en anslutning asynkront.
Den använder parametrar för varje värde som skickas till databasen.
Hanterar SQL-fel och avbrytningar.

För att bygga in samma dataåtkomst i ett webb-API, se Quickstart: Använd Microsoft.Data.SqlClient i en ASP.NET Core-app. Den använder samma tabell.

Förutsättningar

.NET 10 SDK eller en senare stödd .NET SDK. SDK:n körs på Windows, Linux och macOS. SDK:n bygger också .NET Framework-versionen av exemplet, som endast körs på Windows och kräver .NET Framework 4.8.1. Använd .NET-versionen för ny utveckling.
En kodredigerare. Du kan använda Visual Studio, Visual Studio Code eller vilken editor som helst tillsammans med .NET CLI. Den här artikeln använder kommandoradsgränssnittet för .NET.
En databas som du kan ansluta till. Om du inte har ett, skapa ett genom att använda följande alternativ.

Skapa en SQL-databas

Skapa eller koppla till en SQL-databas på en av följande plattformar:

Skapa en SQL-databas på några minuter med hjälp av Azure-portalen

Databasbehörigheter

Appen skapar sin egen tabell, så du behöver inte exempeldata. Databasidentiteten behöver behörighet för att ansluta och för att skapa, infoga och välja från en tabell.

För en SQL-databas i Microsoft Fabric, kopiera server- och databasnamnen från SQL-databasobjektet. Använd inte SQL-analysterminalen. Identiteten behöver behörigheten Läs objekt, vilket en arbetsyteroll eller en objektbehörighet kan ge. För mer information, se Autentisering i SQL-databas. SQL-autentisering stöds inte.

För Azure SQL Database, konfigurera Microsoft Entra ID-autentisering och databasåtkomst.

I en tom mapp, kör dessa kommandon:

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

Konsolmallen erbjuder inte .NET Framework-mål. Skapa projektet i en tom mapp:

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

Ersätt innehållet i SqlClientQuickstart.csproj med denna projektfil:

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

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

</Project>

Lägg sedan till paketen:

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

Tilläggspaketet tillhandahåller drivrutinens Microsoft Entra-autentiseringslägen, såsom služba Active Directory Default. Om din app endast använder SQL-autentisering eller Windows-integrerad autentisering kan du utelämna Microsoft.Data.SqlClient.Extensions.Azure. När du använder båda paketen, se till att de har samma version. För andra installationsalternativ, se Installera, uppdatera och distribuera Microsoft.Data.SqlClient.

Konfigurera anslutningen

Ställ in miljövariabeln SQL_CONNECTION_STRING för din databas. Lägg inte ett lösenord, en åtkomsttoken eller en anslutningssträng för produktion i källkod.

Välj en av dessa startpunkter och byt ut platshållarna.

Azure SQL eller SQL-databas i Fabric med Microsoft Entra ID

Logga in med en Microsoft Entra-identitet som har tillgång till databasen. För lokal utveckling, använd ett utvecklarverktyg som Azure CLI:

az login

Kopiera exakta server- och databasnamn från Azure SQL-databasen eller SQL-databasen i Fabric. För PowerShell:

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

För Bash:

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

För en app som hostas i Azure, ge dess hanterade identitet åtkomst till databasen och använd sedan Authentication=služba Active Directory Managed Identity. För andra alternativ, se Microsoft Entra-autentisering med Microsoft.Data.SqlClient.

SQL Server med SQL-autentisering

Använd servern, porten, databasen och inloggningen för din SQL Server-instans. Följande exempel gäller en lokal utvecklingsinstans som inte har ett betrott certifikat. För PowerShell:

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

För 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 Hoppar över validering av servercertifikat. Använd det endast med en lokal utvecklingsinstans som inte har ett betrodd certifikat. För delade eller produktionsinstanser av SQL Server, installera ett certifikat som klienten litar på, använd servernamnet på det certifikatet och ta bort TrustServerCertificate=true. Mer information finns i Kryptering och certifikatverifiering i Microsoft.Data.SqlClient.

Om din miljö stödjer Windows-integrerad autentisering eller Kerberos, ersätt User ID och Password med Integrated Security=true. För installationskrav, se SQL Server och Windows-autentisering.

Lägg till koden

.NET
.NET Framework

Ersätt innehållet i Program.cs med den här koden:

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

Ersätt innehållet i Program.cs med den här koden:

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

Kör appen

Kör appen:

dotnet run

Första gången du kör appen är tabellen tom och utdata ser ut så här:

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)

Dina tidsstämplar skiljer sig åt. Varje senare körning lägger till två rader till, så ID:n fortsätter från förra körningen.

Om appen inte kan ansluta skriver den ut SQL-felnumret, klientanslutnings-ID:t, felmeddelandet och det inre undantagsmeddelandet, och avslutar sedan med kod 3. För vanliga fel, se Felsökning.

Så här fungerar koden

OpenAsync, ExecuteNonQueryAsync, ExecuteScalarAsync, ExecuteReaderAsync och ReadAsync alla får samma CancellationToken. Tryck Ctrl+C för att avbryta det pågående arbetet.
Insert-kommandot skapas en gång och körs en gång för varje meddelande. Endast parametervärdet ändras.
Parametertyperna och storlekarna matchar tabellkolumnerna. Parametrar används för att skicka värden separat från SQL-texten, vilket förhindrar att dessa värden ändrar kommandot och hjälper SQL Server att återanvända frågeplaner.
OUTPUT INSERTED.Id returnerar det nya identitetsvärdet, så ExecuteScalarAsync returnerar ID:t utan en andra förfrågan.
await using frigör kommandona, läsaren och anslutningen, även när ett undantag inträffar. När anslutningen frigörs returneras den till anslutningspoolen. .NET Framework-versionen använder using-block, eftersom dessa typer inte implementerar IAsyncDisposable på .NET Framework.
SqlException.Number identifierar felet och ClientConnectionId låter dig matcha ett klienthaveri med serversidans loggar. För anslutningsfel på Linux och macOS finns orsaken ofta bara i InnerException, till exempel ett certifikatvalideringsfel bakom den generiska error: 35 - An internal exception was caught.

Troubleshoot

Fel eller symptom	Vad du bör kontrollera	Mer information
`The certificate chain was issued by an authority that is not trusted`på Windows. På Linux och macOS följs `error: 35 - An internal exception was caught` av det inre undantaget `Certificate failed chain validation` med `UntrustedRoot`.	Servercertifikatet betros inte av klienten, eller så stämmer servernamnet i reťazec pripojenia inte med certifikatet. Installera ett betrott certifikat. Använd `TrustServerCertificate=true` endast med en lokal utvecklingsinstans.	Kryptering och certifikatvalidering i Microsoft. Data.SqlClient
`SQL error 18456` med `Login failed for user`	Användarnamnet, lösenordet eller databasnamnet är fel, eller så har inloggningen inte tillgång till databasen. För Microsoft Entra ID, kontrollera att identiteten har lagts till som databasanvändare.	Felsökningsguide för SqlClient
`A network-related or instance-specific error occurred` med `error: 26`, `error: 40`, eller `The wait operation timed out`. På Linux och macOS visas en timeout `SQL error 258` med `error: 35`, följt av det inre undantaget `The connection attempt timed out`.	Servernamnet eller porten är fel, servern accepterar inte fjärranslutningar via TCP, eller så blockerar en brandvägg porten. För Azure SQL, kontrollera serverbrandväggsreglerna.	Felsökningsguide för SqlClient
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	Anslutningssträngen använder ett `služba Active Directory` autentiseringsläge, men projektet refererar inte till `Microsoft.Data.SqlClient.Extensions.Azure`. Lägg till paketet med samma version som `Microsoft.Data.SqlClient`.	Microsoft Entra-autentisering flyttar till ett tilläggspaket i 7.0
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	Projektet refererar inte till paketet `Microsoft.Data.SqlClient` . Kör `dotnet add package`-kommandot från mappen som innehåller projektfilen.	Installera, uppdatera och distribuera Microsoft. Data.SqlClient
Återställ rapporter `NU1902` eller `NU1903` för ett transitivt paket	Ett paket som drivrutinen är beroende av har ett publicerat säkerhetsmeddelande.	Åtgärder när paket med kända sårbarheter rapporteras

Rensa resurser

Tabellen stannar kvar i din databas efter att appen avslutats. Om du inte planerar att fortsätta med ASP.NET Core quickstart, som använder samma tabell, ta bort den med valfritt frågeverktyg:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Ta sedan bort projektmappen. Från föräldramappen, för PowerShell:

Remove-Item -Recurse -Force SqlClientQuickstart

För Bash:

rm -rf SqlClientQuickstart

Rensa miljövariabeln så att reťazec pripojenia inte stannar kvar i din shell-session. För PowerShell, kör Remove-Item Env:\SQL_CONNECTION_STRING. För Bash, kör unset SQL_CONNECTION_STRING.

Använd mönstret i en applikation

Håll dessa gränser när du flyttar provet till ett API, en tjänst, en skrivbordsapp eller en bakgrundsprocess:

Ladda anslutningsinformation via appens konfigurationssystem.
Öppna en anslutning för ett kort arbetsmoment och avveckla den sedan.
Skicka en CancellationToken till anropen open, command och reader.
Ställ in kommandotimeouts baserat på operationen.
Använd parametrar för varje värde som kommer utanför SQL-satsen.
Logga SqlException.Number och ClientConnectionId utan inloggningsuppgifter eller åtkomsttoken.
Lägg till omprövningar endast vid tillfälliga fel och endast när upprepning av operationen är säker.

Nästa steg

Feedback

Var den här sidan till hjälp?

Uppdaterades senast 2026-10-23

Snabbstart: Ansluta och köra frågor med Microsoft.Data.SqlClient

Förutsättningar

Skapa en SQL-databas

Databasbehörigheter

Skapa projektet

Konfigurera anslutningen

Azure SQL eller SQL-databas i Fabric med Microsoft Entra ID

SQL Server med SQL-autentisering

Lägg till koden

Kör appen

Så här fungerar koden

Troubleshoot

Rensa resurser

Använd mönstret i en applikation

Nästa steg

Feedback

Ytterligare resurser