Hızlı başlangıç: Bir ASP.NET Core uygulamasında Microsoft.Data.SqlClient kullanma

Bu hızlı başlangıçta, Microsoft.Data.SqlClient 7.1.1 ile bir ASP.NET Core minimal API oluşturuyorsunuz.

Boş bir klasörle, .NET SDK'sıyla ve bilgisayarınızdan ulaşabileceğiniz bir SQL Server veya Azure SQL veritabanı ile başlarsınız. Sonuç olarak, bir tabloya mesaj ekleyen ve bunu kimliğine göre geri okuyan bir web API’si elde edersiniz.

Bu süreçte, uygulama:

  • ASP.NET Core yapılandırmasından bağlantı dizesi'i okur. Yerel geliştirme için değer kullanıcı sırlarından gelir, bu yüzden proje klasörünüze girmez.
  • Bir veri sınıfını bağımlılık enjeksiyonu ile kaydeder.
  • Her istek için bir bağlantı açıp kapatır, bu da varsayılan bağlantı havuzunun fiziksel bağlantıları yeniden kullanmasına olanak tanır.
  • İsteğin CancellationToken öğesini her veritabanı çağrısına iletir.

Uygulama, dbo.SqlClientQuickstart ile aynı tabloyu kullanıyor. Önce hızlı başlangıçlardan herhangi birini yapabilirsin.

Prerequisites

Mevcut ASP.NET Core, .NET üzerinde çalışıyor, .NET Framework üzerinde değil. .NET Framework'ten sürücüyü kullanmak için .NET Framework projeleri sayfasına bakınız.

Veritabanı kimliği, bağlanmak ve bir tablo oluşturmak, bir tabloya veri eklemek ve tablodan veri seçmek için izin gerektirir.

Projeyi oluşturma

Boş bir klasörde şu komutları çalıştırın:

dotnet new web --framework net10.0 --name SqlClientWebQuickstart
cd SqlClientWebQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1
dotnet user-secrets init

dotnet user-secrets init Proje dosyasına UserSecretsId ekler. ASP.NET Core, kullanıcı sırlarını yalnızca uygulama Development ortamında çalıştığında yükler; bu ortam, dotnet run için varsayılan ortamdır.

Uzantı paketi, sürücünün Microsoft Entra kimlik doğrulama modlarını sağlar. Uygulamanız yalnızca SQL kimlik doğrulaması kullanıyorsa, Microsoft.Data.SqlClient.Extensions.Azure öğesini atlayabilirsiniz. Her iki paketi de kullandığınızda, versiyonlarını aynı tutun.

Bağlantıyı yapılandırma

Connection string'i ConnectionStrings:Quickstart kullanıcı sırlarında sakla. Kullanıcı sırları proje klasöründe değil, kullanıcı profilinizde saklanır, bu yüzden kaynak denetimine işlenmezler. Parola veya üretim bağlantı dizesi koymayınappsettings.json.

Bu başlangıç noktalarından birini seçin ve yer tutucuları değiştirin. dotnet user-secrets set komutları, PowerShell ve Bash için tek tırnak kullanır. Komut İstemi'nde bunun yerine çift tırnak kullanın, çünkü Komut İstemi tek tırnakları anahtar ve değerin bir parçası olarak saklar.

Azure SQL with Microsoft Entra ID

Veritabanına erişimi olan bir Microsoft Entra kimliğiyle giriş yapın. Yerel geliştirme için, Azure CLI gibi bir geliştirici aracı kullanın:

az login

Sonra bağlantı dizesi'i kaydet. Azure SQL veritabanından tam sunucu ve veritabanı adlarını kopyalayın. Aynı bağlantı dizesi, konsol hızlı başlangıcında açıklandığı gibi SQL veritabanı öğesinden sunucu ve veritabanı adlarını kullandığınızda Microsoft Fabric'te SQL veritabanı için de çalışır.

dotnet user-secrets set 'ConnectionStrings:Quickstart' 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;Connect Timeout=30'

Bu bağlantı dizesi bir gizli anahtar içermez. Active Directory Default geliştirici oturum açma bilgilerinizi yerel olarak kullanır. Azure App Service veya Azure Container Apps'e dağıttığınızda, uygulamanın yönetilen kimliğine veritabanı erişimi verin, değeri Authentication=Active Directory Managed Identity olarak değiştirin ve bunu ana bilgisayarın yapılandırmasında ConnectionStrings__Quickstart olarak ayarlayın. Diğer seçenekler için bkz. Microsoft.Data.SqlClient ile Microsoft Entra kimlik doğrulaması.

SQL kimlik doğrulama ile yerel SQL Server

Güvenilir sertifikası olmayan yerel bir geliştirme örneği için bağlantı dizesi'i sakla. PowerShell ve Bash'in şifredeki bir $ karakterini yorumlamasını önlemek için tek tırnak kullanın.

dotnet user-secrets set 'ConnectionStrings:Quickstart' 'Server=tcp:<server>,1433;Database=<database>;User ID=<user-id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Caution

TrustServerCertificate=true sunucu sertifikası doğrulamasını atlar. Bunu yalnızca yerel bir geliştirme ortamıyla kullanın. Paylaşılan veya üretim SQL Server örnekleri için, istemcinin güvendiği bir sertifika yükleyin ve TrustServerCertificate=true öğesini kaldırın. Daha fazla bilgi için bkz. Microsoft.Data.SqlClient Şifreleme ve sertifika doğrulaması.

Kodu ekle

öğesinin içeriğini Program.cs şu kodla değiştirin:

using System.Data;
using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<MessageStore>();

var app = builder.Build();

await app.Services.GetRequiredService<MessageStore>()
    .EnsureTableAsync(app.Lifetime.ApplicationStopping);

app.MapPost("/messages", async (
    NewMessage input, MessageStore store, CancellationToken cancellationToken) =>
{
    if (string.IsNullOrWhiteSpace(input.Text) || input.Text.Length > 200)
    {
        return Results.BadRequest("Text must be 1 to 200 characters.");
    }

    Message message = await store.AddAsync(input.Text, cancellationToken);
    return Results.Created($"/messages/{message.Id}", message);
});

app.MapGet("/messages/{id:int}", async (
    int id, MessageStore store, CancellationToken cancellationToken) =>
    await store.GetAsync(id, cancellationToken) is Message message
        ? Results.Ok(message)
        : Results.NotFound());

app.Run();

record NewMessage(string Text);

record Message(int Id, string Text, DateTimeOffset CreatedAt);

sealed class MessageStore(IConfiguration configuration)
{
    private readonly string _connectionString =
        configuration.GetConnectionString("Quickstart")
        ?? throw new InvalidOperationException(
            "Set the ConnectionStrings:Quickstart configuration value.");

    public async Task EnsureTableAsync(CancellationToken cancellationToken)
    {
        const string sql = """
            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 connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        await command.ExecuteNonQueryAsync(cancellationToken);
    }

    public async Task<Message> AddAsync(
        string text, CancellationToken cancellationToken)
    {
        const string sql = """
            INSERT INTO dbo.SqlClientQuickstart (Message)
            OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt
            VALUES (@message);
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@message", SqlDbType.NVarChar, 200).Value = text;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        await reader.ReadAsync(cancellationToken);
        return new Message(
            reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2));
    }

    public async Task<Message?> GetAsync(
        int id, CancellationToken cancellationToken)
    {
        const string sql = """
            SELECT Id, Message, CreatedAt
            FROM dbo.SqlClientQuickstart
            WHERE Id = @id;
            """;

        await using var connection = new SqlConnection(_connectionString);
        await connection.OpenAsync(cancellationToken);
        await using var command =
            new SqlCommand(sql, connection) { CommandTimeout = 30 };
        command.Parameters.Add("@id", SqlDbType.Int).Value = id;

        await using SqlDataReader reader =
            await command.ExecuteReaderAsync(cancellationToken);
        return await reader.ReadAsync(cancellationToken)
            ? new Message(
                reader.GetInt32(0), reader.GetString(1), reader.GetDateTimeOffset(2))
            : null;
    }
}

Uygulamayı çalıştırma

Uygulamayı sabit bir portta başlatın:

dotnet run --urls http://localhost:5000

Başlangıçta, tablo yoksa uygulama tabloyu oluşturur. Uygulama hazır olduğunda, çıktı şu satırları içerir:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development

Uygulama veritabanına ulaşamazsa, başlangıçta SqlException hatasıyla durur. Yaygın nedenler için Sorun Giderme bölümüne bakınız.

API'yi çağırma

Uygulamayı çalışır bırakın ve ikinci bir terminal açın. POST isteğiyle bir mesaj ekleyin ve ardından bunu GET isteğiyle kimliğine göre tekrar okuyun. Eğer tabloda zaten, örneğin konsol hızlı başlangıcından gelen satırlar varsa, GET isteğinde id yerine POST isteğinizin döndürdüğü 1 değerini kullanın.

PowerShell için:

Invoke-RestMethod -Method Post -Uri http://localhost:5000/messages -ContentType application/json -Body (@{ text = 'Hello from ASP.NET Core' } | ConvertTo-Json)
Invoke-RestMethod http://localhost:5000/messages/1

PowerShell, her JSON yanıtını bir tablo olarak biçimlendirir. İlk satır 201 Created POST talebine verilen yanıt, ikinci satır ise GET cevabıdır:

id text                    createdAt
-- ----                    ---------
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00
 1 Hello from ASP.NET Core 2026-10-21T00:04:43.3588978+00:00

Windows PowerShell 5.1, createdAt öğesini API'nin döndürdüğü dize olarak gösterir. PowerShell 7, bunu yerel saatte bir tarihe dönüştürür, örneğin 10/20/2026 7:04:43 PM.

Windows PowerShell'de curl, curl seçeneklerini kabul etmeyen Invoke-WebRequest için bir takma addır. PowerShell komutlarını kullanın veya curl.exe öğesini Komut İstemi'nden çalıştırın.

Komut İstemi için:

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d "{\"text\":\"Hello from ASP.NET Core\"}"
curl http://localhost:5000/messages/1

Komut İstemi tek tırnak karakterlerini alıntı karakteri olarak kabul etmez, bu yüzden JSON gövdesi ters eğik çizgilerle escape edilen çift tırnak kullanır. Her komut JSON yanıtını yazdırıyor:

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-21T00:05:15.4936763+00:00"}

Bash için:

curl -X POST http://localhost:5000/messages -H "Content-Type: application/json" -d '{"text":"Hello from ASP.NET Core"}'
curl http://localhost:5000/messages/1

{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}
{"id":1,"text":"Hello from ASP.NET Core","createdAt":"2026-10-20T20:44:17.8634925+00:00"}

Kimlikleriniz ve zaman damgalarınız farklıdır. Eğer önce konsol hızlı başlangıcını çalıştırdıysanız, kimlikler onun satırlarından devam eder. Var olmayan bir kimlik için yapılan istek 404 Not Found döndürür. Boş bir mesaj 400 Bad Request döndürür.

Uygulamayı durdurmak için ilk terminalde Ctrl+C tuşuna basın.

Kod nasıl çalışır?

  • Uygulama, MessageStore öğesini singleton olarak kaydeder. Yalnızca IConfiguration içinden bir kez okuduğu bağlantı dizesi'i tutar. Bağlantısı yok.
  • Her yöntem bir SqlConnection oluşturur, açar, bir komut çalıştırır ve onu await using ile serbest bırakır. Disposing fiziksel bağlantıyı bağlantı havuzuna geri döndürür ve sonraki istek bunu tekrar kullanır. Bağlantı havuzu varsayılan olarak açık, yani yapılandırmanıza gerek yok. Ayarlama seçenekleri için bkz. Microsoft.Data.SqlClient ile SQL Server bağlantı havuzu.
  • ASP.NET Core, CancellationToken parametresini isteğe bağlar. İstemci bağlantıyı keserse, token açma, komut ve okuma işlemlerini iptal eder.
  • @message ve @id parametreleri sütun türleri ve boyutlarıyla eşleşir. API, değeri veritabanına göndermeden önce mesaj uzunluğunu doğrular.
  • OUTPUT INSERTED.Id, INSERTED.Message, INSERTED.CreatedAt eklenen satırı, sunucu tarafından oluşturulan kimlik ve zaman damgası dahil olmak üzere, ikinci bir sorgu olmadan döndürür.
  • Diğer ortamlarda ASP.NET Core, aynı ConnectionStrings:Quickstart anahtarını ConnectionStrings__Quickstart gibi ortam değişkenlerinden veya Azure Key Vault gibi başka bir yapılandırma sağlayıcısından okur.

Troubleshoot

Hata veya belirti Denetlenecek şeyler Daha fazla bilgi
Set the ConnectionStrings:Quickstart configuration value. Uygulama bağlantı dizesi'i bulamadı. Proje klasöründe dotnet user-secrets list komutunu çalıştırın ve uygulamanın Development ortamında çalıştığını kontrol edin. ASP.NET Core
System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault' Başlangıçta Connection string, Active Directory kimlik doğrulama modunu kullanıyor, ancak proje Microsoft.Data.SqlClient.Extensions.Azure başvurusuna sahip değil. Paketi Microsoft.Data.SqlClient ile aynı sürümde ekleyin. Microsoft Entra doğrulaması 7.0'da bir uzantı paketine taşınıyor
SqlException Başlangıçta Uygulama bağlanamadı veya tabloyu oluşturamadı. Hata numarası, başarısız giriş için 18456 gibi nedeni belirtir. Konsol hızlı başlatmasında sorun giderme
415 Unsupported Media Type İstek Content-Type: application/json ayarlamaz. Minimal API'ler hızlı başvuru
Cannot bind parameter 'Headers' Windows PowerShell'de curl komutunu çalıştırdınız; burada curl, Invoke-WebRequest komutunu çalıştırır. API'yi çağır bölümündeki PowerShell komutlarını kullanın. Invoke-RestMethod
''' is an invalid start of a value Bash curl komutunu Komut İstemi'nde çalıştırdınız, bu komut tek tırnak işaretlerini istek gövdesinin bir parçası olarak gönderiyor. API'yi çağır bölümünde Komut İstemi komutlarını kullanın. API'yi çağır

Kaynakları temizle

Herhangi bir sorgu aracıyla tabloyu silin:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Depolanan bağlantı dizesi'i kaldırın. Proje klasöründen şunu çalıştırın:

dotnet user-secrets clear

Sonra proje klasörünü sil. Ana klasörden, PowerShell'de aşağıdaki komutu çalıştırın:

Remove-Item -Recurse -Force SqlClientWebQuickstart

Bash için:

rm -rf SqlClientWebQuickstart

Sonraki Adımlar

  • Son güncelleştirme: