SqlBatch ile birden fazla komutu çalıştır

SqlConnection kullanarak SqlBatchCommand nesnelerinden oluşan sıralı bir koleksiyonu tek bir açık SqlBatch bağlantı üzerinden gönderin. Her toplu komutun kendi komut metni, komut türü, parametreleri, komut davranışı ve etkilenen satır sayısı sonucu vardır.

Bir uygulamanın birlikte göndermek istediği ayrı komutları olduğunda SqlBatch kullanın. İş tek bir ifade veya saklı yordam olduğunda bir parametreli SqlCommand kullanın. Büyük satır kümeleri için SqlBulkCopy veya tablo değerli bir parametre kullanın.

Bu makaledeki örnekler, connection adlı açık bir SqlConnection'ın AdventureWorks örnek veritabanını hedeflediğini varsaymaktadır.

C# örnekleri using Microsoft.Data.SqlClient; gerektirir. SqlDbType veya CommandBehavior kullanan örnekler ayrıca using System.Data; gerektirir. DbDataReader kullanan örnekler için using System.Data.Common; gereklidir.

Sürüm ve platform desteği

Örnekler Microsoft.Data.SqlClient 7.1.0'ı hedefliyor. Uygulamanız için Microsoft.Data.SqlClient destek yaşam döngüsünün desteklediği bir paket sürümü ve hedef çerçeve seçin.

SqlBatch, modern .NET üzerinde DbBatch öğesinden türetilir. Microsoft.Data.SqlClient ayrıca .NET Framework ve .NET Standard 2.0 paket varlıklarında SqlBatch öğesini de kullanıma sunar. Genel API yüzeyi hedef çerçevesine göre değişebilir, bu yüzden yayınladığınız her hedef için uygulamayı derleyin.

Toplu görev oluşturun

Açık bağlantı için bir toplu iş oluştur ve ardından komutları çalıştırma sırasına göre ekle:

using var batch = new SqlBatch(connection);
batch.BatchCommands.Add(new SqlBatchCommand("""
    SELECT TOP (3) ProductID, Name
    FROM Production.Product
    ORDER BY ProductID;
    """));
batch.BatchCommands.Add(new SqlBatchCommand("""
    SELECT TOP (3) SalesOrderID, OrderDate
    FROM Sales.SalesOrderHeader
    ORDER BY SalesOrderID;
    """));

using DbDataReader reader = batch.ExecuteReader();
do
{
    while (reader.Read())
    {
        Console.WriteLine($"{reader.GetValue(0)} | {reader.GetValue(1)}");
    }
}
while (reader.NextResult());

CommandType.Text varsayılan değerdir. Bir toplu komutu CommandType.StoredProcedure saklı yordamı için ayarlayın. Ayarlama CommandType.TableDirectArgumentOutOfRangeException oluşturur.

Toplu komutlara parametreler ekle

Parametreler bir bireye SqlBatchCommandaittir . İki toplu komutta aynı yer tutucu adı bir değeri paylaşmaz:

using var batch = new SqlBatch(connection);

var products = new SqlBatchCommand("""
    SELECT ProductID, Name
    FROM Production.Product
    WHERE ProductSubcategoryID = @id
    ORDER BY ProductID;
    """);
products.Parameters.Add("@id", SqlDbType.Int).Value = 2;
batch.BatchCommands.Add(products);

var orders = new SqlBatchCommand("""
    SELECT SalesOrderID, OrderDate
    FROM Sales.SalesOrderHeader
    WHERE SalesPersonID = @id
    ORDER BY SalesOrderID;
    """);
orders.Parameters.Add("@id", SqlDbType.Int).Value = 279;
batch.BatchCommands.Add(orders);

using DbDataReader reader = batch.ExecuteReader();

Her parametrenin SQL tipini ve uygulanabilir boyutu, kesinliği ve ölçeği veritabanı sözleşmesinden ayarlayın. Daha fazla bilgi için bkz. Parametreleri yapılandırma.

Veri değiştirme komutlarını çalıştır

ExecuteNonQuery veya ExecuteNonQueryAsync, toplu işlem verileri değiştirdiğinde ve sonuç satırlarına ihtiyacınız olmadığında kullanın. Geri dönen değer, satır sayıları mevcut olduğunda etkilenen toplam satır sayısıdır. Yürütüldükten sonra, her komutun RecordsAffected öğesi kendi sayısını bildirir.

Bu örnek değişikliklerini geri almaktadır:

using SqlTransaction transaction = connection.BeginTransaction();
using var batch = new SqlBatch(connection, transaction);

var firstUpdate = new SqlBatchCommand("""
    UPDATE Sales.SalesOrderHeader
    SET Status = @status
    WHERE SalesOrderID = @salesOrderId;
    """);
firstUpdate.Parameters.Add("@status", SqlDbType.TinyInt).Value = 2;
firstUpdate.Parameters.Add("@salesOrderId", SqlDbType.Int).Value = 43659;
batch.BatchCommands.Add(firstUpdate);

var secondUpdate = new SqlBatchCommand("""
    UPDATE Sales.SalesOrderHeader
    SET Status = @status
    WHERE SalesOrderID = @salesOrderId;
    """);
secondUpdate.Parameters.Add("@status", SqlDbType.TinyInt).Value = 2;
secondUpdate.Parameters.Add("@salesOrderId", SqlDbType.Int).Value = 43660;
batch.BatchCommands.Add(secondUpdate);

int totalRows = batch.ExecuteNonQuery();
Console.WriteLine($"Total rows: {totalRows}");

foreach (SqlBatchCommand command in batch.BatchCommands)
{
    Console.WriteLine(command.RecordsAffected);
}

transaction.Rollback();

Birden fazla sonucu okuyun

Herhangi bir komut satırlar döndürdüğünde ExecuteReader veya ExecuteReaderAsync kullanın. Okuyucu sonuçları toplu komut sırasıyla görüntüler. NextResult veya NextResultAsync çağrısı false dönene kadar arayın.

Bir komut, satır kümesi üretmeyebilir, bir satır kümesi veya birden fazla satır kümesi üretebilir. Bir NextResult çağrının bir SqlBatchCommand ile eşlendiğini varsaymayın.

Komut davranışını kullanın

Okuyucunun sıralı erişime ihtiyacı olduğunda veya bağlantıyı kapatması gerektiğinde toplu düzeyde CommandBehavior öğesini ExecuteReader veya ExecuteReaderAsync öğesine iletin:

using var batch = new SqlBatch(connection);
batch.BatchCommands.Add(new SqlBatchCommand("""
    SELECT DocumentSummary
    FROM Production.Document
    WHERE DocumentSummary IS NOT NULL;
    """));

using DbDataReader reader =
    batch.ExecuteReader(CommandBehavior.SequentialAccess);

char[] buffer = new char[4096];
while (reader.Read())
{
    using TextReader summary = reader.GetTextReader(0);
    int count;
    while ((count = summary.Read(buffer, 0, buffer.Length)) > 0)
    {
        Console.Out.Write(buffer, 0, count);
    }
    Console.WriteLine();
}

Parti seviyesindeki aşırı yüklemeler yalnızca CommandBehavior.Default, CommandBehavior.SequentialAccess, CommandBehavior.CloseConnection ve bu değerlerin kombinasyonlarını kabul eder. Diğer geçerli değerler, örneğin SingleRow, KeyInfo ve ArgumentOutOfRangeException, toplu düzeyindeki bir aşırı yüklemeye geçirildiğinde SchemaOnly atar. Toplu iş düzeyi davranış aşırı yüklemeleri, Microsoft.Data.SqlClient 7.1 sürümünden itibaren kullanılabilir.

SingleRow, SchemaOnly ve KeyInfo gibi seçenekler için CommandBehavior ayarını ayrı bir komutta yapın. SequentialAccess ve CloseConnection için toplu iş düzeyi aşırı yüklemeyi kullanın.

Bir işlem kullanın

SqlBatch komutlarını atomik hale getirmez. Tüm komutlar birlikte commit edilmesi veya geri alınması gerektiğinde açık bir işlem kullanın. Bu örnek geri alınır, böylece AdventureWorks değişmeden kalır:

using SqlTransaction transaction = connection.BeginTransaction();
using var batch = new SqlBatch(connection, transaction);

batch.BatchCommands.Add(new SqlBatchCommand("""
    UPDATE Sales.SalesOrderHeader
    SET Status = 2
    WHERE SalesOrderID = 43659;
    """));
batch.BatchCommands.Add(new SqlBatchCommand("""
    UPDATE Sales.SalesOrderHeader
    SET Status = 2
    WHERE SalesOrderID = 43660;
    """));

batch.ExecuteNonQuery();
transaction.Rollback();

Yalnızca uygulama tam partiyi kabul ettiğinde Rollback yerine Commit çağırın. İşlemi yürütmeden önce atayın. İşlem ve toplu işlem aynı bağlantıyı kullanmalıdır. SqlClient asenkron işlem yöntemlerini override etmez, yani BeginTransactionAsync, CommitAsync ve RollbackAsync senkron olarak tamamlanır. Daha fazla bilgi için bkz. Görev tabanlı SQL işlem yöntemlerini kullanın.

Zaman aşımları, iptal ve hatalarla ilgilenin

Parti için Timeout değerini saniye cinsinden ayarlayın. Toplu işlem, bir bağlantı yapılandırdığınızda bağlantının Command Timeout ayarını kullanır. Aksi takdirde, varsayılan süre 30 saniyedir. 0 değerinin zaman sınırı yoktur ve negatif değerler ArgumentException oluşturur. Çağıran kodun beklemeyi durdurması gerektiğinde, asenkron bir yürütme yöntemine bir iptal belirteci geçirin veya Cancel çağrısını yapın. İptal işlemi garanti edilmez. Operasyon, iptal yürürlüğe girmeden önce tamamlanabilir.

Yürütme başarısız olduğunda, Errors öğesini yakalayın ve SqlException koleksiyonundaki her öğeyi inceleyin. BatchCommand, bu bilgi mevcut olduğunda ilişkili SqlBatchCommand öğesini belirler:

using var batch = new SqlBatch(connection);
batch.BatchCommands.Add(new SqlBatchCommand(
    "SELECT TOP (1) ProductID FROM Production.Product;"));
batch.BatchCommands.Add(new SqlBatchCommand("SELECT 1 / 0;"));

try
{
    using DbDataReader reader = batch.ExecuteReader();
    do
    {
        while (reader.Read())
        {
            Console.WriteLine(reader.GetValue(0));
        }
    }
    while (reader.NextResult());
}
catch (SqlException exception)
{
    Console.WriteLine(
        exception.BatchCommand is null
            ? "The batch failed."
            : $"Failed command: {exception.BatchCommand.CommandText}");
}

Okuyucu yürütülmesi kademelidir. Daha sonraki bir toplu komuttan gelen hata, Read veya NextResult o komuta ilerlediğinde ortaya çıkabilir, bu yüzden okuyucuyu try bloğu içinde işleyin.

Kimlik bilgileri, tokenlar veya hassas veriler içeren parametre değerlerini kaydetmeyin. Hata alanları ve bilgilendirici mesajlar için bkz. Hataları ve mesajları yönet.

İlgili içerik

• Bir komutu çalıştır
• Parametreleri yapılandırma
• SqlDataReader ile veri alın
• Asenkron programlama