Använd Microsoft. Data.SqlClient i en .NET-app

I denna quickstart skapar du en .NET-konsolapplikation som:

• Läser sin reťazec pripojenia från miljön istället för källkoden.
• Öppnar en anslutning asynkront.
• Skapar en tabell om den inte finns.
• Lägger in en rad med ett parameteriserat kommando.
• Läser rader med en parameteriserad fråga.
• Hanterar SQL- och avbokningsfel.

Exemplet använder Microsoft. Data.SqlClient 7.0.3, den nuvarande stabila versionen.

Förutsättningar

Du behöver .NET 10 SDK eller en senare stödd .NET SDK.

Skapa en SQL-databas

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

Quickstart skapar sin egen tabell, så exempeldata behövs inte. 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.

Skapa projektet

Kör följande kommandon:

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

Tilläggspaketet tillhandahåller drivrutinstillhandahållna Microsoft Entra ID-autentiseringslägen. En applikation som endast använder Windows-integrerad autentisering eller SQL-autentisering kan utelämna Microsoft.Data.SqlClient.Extensions.Azure.

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.

Fabric SQL eller Azure SQL med lösenordslös autentisering

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

az login

Kopiera de exakta server- och databasnamnen från SQL-databasobjektet i Fabric eller Azure SQL-databasen. 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 applikation som är värd i Azure och ansluter till Azure SQL, ge dess hanterade identitetsdatabasåtkomst och använd Authentication=služba Active Directory Managed Identitysedan . För andra Microsoft Entra ID-alternativ, se Microsoft Entra ID-autentisering.

SQL Server över TCP

Använd servern, porten, databasen och logga in från din befintliga SQL Server eller den installationsguide du följt. Följande exempel på SQL-autentisering gäller en lokal utvecklingscontainer. 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'

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

Lägg till programkoden

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

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

Parametertyperna och storlekarna matchar tabellkolumnerna. Parametrar skickar värden separat från SQL-text, vilket förhindrar att dessa värden ändrar kommandosyntaxen och hjälper SQL Server att återanvända frågeplaner.

await using frigör läsaren och anslutningen även om ett undantag inträffar. Att kassera anslutningen returnerar dess fysiska anslutning till anslutningspoolen istället för att hålla en anslutning öppen under applikationens livslängd.

Starta programmet

Kör programmet:

dotnet run

Applikationen skriver ut raden som den infogade:

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

Identitetsvärdet och tidsstämpeln skiljer sig åt i varje databas.

Om anslutningen misslyckas, använd SQL-felnumret och klientanslutnings-ID från felutdatan. Kontrollera server- och databasnamn, nätverksåtkomst, databasbehörigheter, autentiseringsinställningar och certifikatkonfiguration. Lägg inte till TrustServerCertificate=true i en Azure SQL-anslutning eller en produktionsanslutning som en allmän lösning på anslutningsproblem.

Använd mönstret i en applikation

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

• Ladda anslutningsinformation via applikationens 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

• Välj och skapa en anslutningssträng.
• Konfigurera anslutningsbeteende.
• Hantera anslutningens livscykel.
• Använd SQL Server connection pooling.
• Konfigurera logik för återförsök.
• Använd kommandon och parametrar.