Microsoft ADO.NET sürücüsü Microsoft Fabric Data Engineering için

ADO.NET, .NET ekosisteminde uygulamaların veritabanlarından ve büyük veri platformlarından verilere bağlanmasını ve verilerle çalışmasını sağlayan yaygın olarak benimsenen bir veri erişim teknolojisidir.

Microsoft ADO.NET Driver for Fabric Data Engineering, standart ADO.NET kalıplarının güvenilirliği ve sadeliğiyle Fabric'te Spark iş yüklerini bağlamanıza, sorgulamanıza ve yönetmenize olanak tanır. Fabric'in Livy API'leri üzerine inşa edilen sürücü, tanıdık DbConnection, DbCommand, ve DbDataReader soyutlamalar kullanarak .NET uygulamalarınıza güvenli ve esnek Spark SQL bağlantısı sağlar.

Temel özellikler

ADO.NET API'leri: Spark SQL bağlantısı için tanıdık DbConnection, DbCommand, DbDataReader, DbParameter, ve DbProviderFactory soyutlamalar
Microsoft Entra Id Kimlik Doğrulaması: Azure CLI, etkileşimli tarayıcı, istemci kimlik bilgileri, sertifika tabanlı ve erişim belirteci kimlik doğrulaması gibi birden çok kimlik doğrulama akışı
Spark SQL Yerel Sorgu Desteği: Parametreli sorgularla Spark SQL deyimlerinin doğrudan yürütülmesi
Kapsamlı Veri Türü Desteği: Karmaşık türler (ARRAY, MAP, STRUCT) dahil olmak üzere tüm Spark SQL veri türleri için destek
Bağlantı Havuzu: Gelişmiş performans için yerleşik bağlantı havuzu yönetimi
Oturumu Yeniden Kullanma: Başlangıç gecikme süresini azaltmak için verimli Spark oturum yönetimi
Yüksek eşzamanlı oturumlar: Eşzamanlı olarak kiralanan HC oturumları için ayrı REPL'ler kullanarak paylaşılan Fabric Livy kapasitesini kullanmayı seçin
Async Prefetch: Büyük sonuç kümeleriyle gelişmiş performans için arka plan verilerini yükleme
Otomatik yeniden bağlanma: Bağlantı arızalarından sonra klasik oturum kurtarılması; HC hataları uygulama kontrollü yeniden deneme için ortaya çıkar

Uyarı

Açık kaynak Apache Spark'ta veritabanı ve şema eş anlamlı olarak kullanılır. Örneğin, bir Fabric not defterinde SHOW SCHEMAS ya da SHOW DATABASES komutunu çalıştırmak aynı sonucu verir — lakehouse’taki tüm şemaların bir listesini döndürür.

Önkoşullar

Microsoft ADO.NET Driver for Fabric Data Engineering'i kullanmadan önce, aşağıdaki özelliklere sahip olduğunuzdan emin olun:

.NET Çalışma Zamanı: .NET 8.0 veya üzeri
Fabric Erişimi: Veri Mühendisliği yeteneklerine sahip bir Fabric çalışma alanına erişim
Azure Entra Id Kimlik Bilgileri: Kimlik doğrulaması için uygun kimlik bilgileri
Çalışma Alanı ve Lakehouse Kimlikleri: Fabric çalışma alanınız ve lakehouse'unuz için GUID tanımlayıcıları
Azure CLI (isteğe bağlı): Azure CLI kimlik doğrulama yöntemi için gereklidir

İndirme, ekleme, başvuru ve doğrulama

NuGet paketini indirme

Önemli

Bu makalede belgelenen alıntılanan çok değerli HcConfOverrides sözdizimi için 2.0.1 NuGet paketi veya daha yeni bir versiyon gereklidir.

Projenizde NuGet paketine başvurma

İndirilen NuGet paketini projenize ekleyin ve pakete ilişkin bir başvuruyu proje dosyanıza ekleyin:

<ItemGroup>
    <PackageReference Include="Microsoft.Spark.Livy.AdoNet" Version="2.0.1" />
</ItemGroup>

Yüklemeyi doğrulama

Ekleme ve başvurudan sonra paketin projenizde kullanılabilir olduğunu doğrulayın:

using Microsoft.Spark.Livy.AdoNet;

// Verify the provider is registered
var factory = LivyProviderFactory.Instance;
Console.WriteLine($"Provider: {factory.GetType().Name}");

Hızlı başlangıç örneği

using Microsoft.Spark.Livy.AdoNet;

// Connection string with required parameters
string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;";

// Create and open connection
using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

// Execute a query
using var command = connection.CreateCommand();
command.CommandText = "SELECT 'Hello from Fabric!' as message";

using var reader = await command.ExecuteReaderAsync();
if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

Bağlantı dizesi biçimi

Temel biçim

Microsoft ADO.NET Sürücüsü standart ADO.NET bağlantı dizesi biçimini kullanır:

Parameter1=Value1;Parameter2=Value2;...

Gerekli parametreler

Parametre	Açıklama	Example
`Server`	Microsoft Fabric API uç noktası. API sürüm eki olmadan ana bilgisayarı belirtin.	`https://api.fabric.microsoft.com`
`SparkServerType`	Sunucu türü tanımlayıcısı	`Fabric`
`FabricWorkspaceID`	Microsoft Fabric çalışma alanı tanımlayıcısı (GUID)	`4bbf89a8-66bb-443f-91af-df31e6a7560b`
`FabricLakehouseID`	Microsoft Fabric lakehouse tanımlayıcısı (GUID)	`d8faa650-1343-496b-b9cc-d4168a676f90`
`AuthFlow`	Kimlik doğrulama yöntemi	`AzureCli`, `BrowserBased`, `ClientSecretCredential`, , `ClientCertificateCredential`, `AuthAccessToken`, `FileToken`

İsteğe bağlı parametreler

Bağlantı ayarları

Parametre	Türü	Varsayılan	Açıklama
`LivyStatementTimeoutSeconds`	Tamsayı	`600`	Deyimin yürütülmesini bekleme süresi saniye cinsinden
`HttpConnectionTimeoutInSeconds`	Tamsayı	`30`	HTTP bağlantısını bekleme zamanı ve istemci havuzu tükendiğinde uygun bir havuzlu bağlantı için bekleme zamanı.
`SessionName`	Dize	(otomatik)	Spark oturumu için özel ad
`EnvironmentID`	UUID	(yok)	Klasik ve HC oturumları için isteğe bağlı Fabric ortam tanımlayıcısı.
`AutoReconnect`	Boolean	`false`	Klasik oturum kurtarmasını etkinleştirin. HC modunda, eskimiş oturum hatası uygulamaya döndürülür ve arka planda otomatik olarak yeniden yürütülmez.

Bağlantı havuzu ayarları

Parametre	Türü	Varsayılan	Açıklama
`ConnectionPoolEnabled`	Boolean	`true`	Bağlantı havuzunu etkinleştirme
`MinPoolSize`	Tamsayı	`1`	Uyumluluk nedeniyle kabul edildi ancak şu anda önceden tahsis edilmiş veya bakımı yapılan havuz minimumu olarak uygulanmıyor.
`MaxPoolSize`	Tamsayı	`50`	Havuz anahtarı başına en fazla Livy oturumu sayısı.
`ValidateConnections`	Boolean	`true`	Havuzlanmış oturumları, kullanıma alındıklarında uzaktan doğrulayın.
`ValidationTimeoutMs`	Tamsayı	`5000`	Maksimum doğrulama süresi milisaniyeler cinsinden.

Yüksek eşzamanlılık ayarları

Parametre	Türü	Varsayılan	Açıklama
`HcEnabled`	Boolean	`false`	Fabric Livy Yüksek eşzamanlılık modunu etkinleştirin. `SparkServerType=Fabric` gerektirir ve oturum, ekstre, iptal ve temizleme işlemlerini HC uç noktaları üzerinden yönlendirir.
`HcSessionTag`	Dize	(yok)	Paylaşılan oturum için isteğe bağlı paketleme ipucu. Değeri atlarsanız veya boş ya da sadece boşluk içeren bir değer girerseniz, sürücü bir etiket göndermez.
`HcConfOverrides`	Dize	(yok)	HC oturumu oluşturma için noktalı virgülle ayrılmış, izin verilenler listesine alınmış Spark yapılandırma geçersiz kılmaları. Birden fazla geçersizleştirme içerdiğinde tam değeri alıntılayın.
`hcAcquireTimeoutSeconds`	Tamsayı	`300`	HC edinme/oturuma hazır zaman aşımı (saniye cinsinden) (120..3600).
`hcAcquirePollingIntervalMs`	Tamsayı	`1000`	HC anket aralığını milisaniye cinsinden alır (50..30000 kabul edildi, çalışma zamanı kelepçesi 100...5000).

Kayıt ayarları

Parametre	Türü	Varsayılan	Açıklama
`LogLevel`	Dize	`Information`	Günlük düzeyi: `Trace`, `Debug`, `Information`, `Warning`, `Error`
`LogFilePath`	Dize	`%LOCALAPPDATA%\FabricSparkAdoNet\Logs` Windows'ta	Dosya tabanlı loglama yolu.

Sürücüler arası takma adlar: Sürücü, yerel ADO.NET adlarına ek olarak JDBC ve ODBC özellik adlarını kabul eder (örneğin, WorkspaceIdFabricWorkspaceID haritası, LakehouseIdFabricLakehouseID haritası). Tüm özellik adları büyük/küçük harfe duyarlı değildir.

Örnek bağlantı dizeleri

Temel bağlantı (Azure CLI kimlik doğrulaması)

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli

Yüksek eşzamanlı bağlantı

Microsoft Fabric bağlantıları için yüksek eşzamanlılık mevcuttur. SetHcEnabled=true; standart ADO.NET bağlantı ve komut API'leri değişmeden kalır. Server için sürümsüz Fabric API ana bilgisayarını kullanın; sürücü, HC uç noktasını oluştururken varsayılan olarak FabricVersion=v1 ve LivyApiVersion=2023-12-01 kullanır.

using Microsoft.Spark.Livy.AdoNet;

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;" +
    "HcEnabled=true;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

using var command = connection.CreateCommand();
command.CommandText = "SELECT 1 AS value";

object? result = await command.ExecuteScalarAsync();
Console.WriteLine($"Result: {result}");

Tam yapılandırma rehberliği için High-Concurrency (HC) Modu bölümüne bakınız.

Bağlantı havuzu seçenekleriyle

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli;ConnectionPoolEnabled=true;MaxPoolSize=10

Otomatik yeniden bağlanma ve günlüğe kaydetme ile

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=AzureCli;AutoReconnect=true;LogLevel=Debug

Kimlik Doğrulaması

Microsoft ADO.NET Sürücüsü, Microsoft Entra ID (eski adıYla Azure Active Directory) aracılığıyla birden çok kimlik doğrulama yöntemini destekler. Kimlik doğrulaması, bağlantı dizesindeki AuthFlow parametresi kullanılarak yapılandırılır.

Kimlik doğrulama yöntemleri

AuthFlow Değeri	Açıklama	En Uygun
`AzureCli`	Azure CLI önbelleğe alınmış kimlik bilgilerini kullanır	Geliştirme ve test
`BrowserBased`	Etkileşimli tarayıcı tabanlı kimlik doğrulaması	Kullanıcıya yönelik uygulamalar
`ClientSecretCredential`	İstemci sırrı ile hizmet asıl	Otomatik hizmetler, arka plan işleri
`ClientCertificateCredential`	Sertifika ile hizmet sorumlusu	Kurumsal uygulamalar
`AuthAccessToken`	Önceden alınan taşıyıcı erişim belirteci	Özel kimlik doğrulama senaryoları

Azure CLI kimlik doğrulaması

En iyi kullanımı: Geliştirme ve test için

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Prerequisites:

Azure CLI yüklü: az --version
Oturum açıldı: az login

Etkileşimli tarayıcı kimlik doğrulaması

En iyi kullanım: Kullanıcıya yönelik uygulamalar

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=BrowserBased;" +
    "AuthTenantID=<tenant-id>;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync(); // Opens browser for authentication

Davranış:

Kullanıcı kimlik doğrulaması için bir tarayıcı penceresi açar
Kimlik bilgileri sonraki bağlantılar için önbelleğe alınır

İstemci Kimlik Bilgileri (Hizmet Sorumlusu) Kimlik Doğrulaması

En iyi: Otomatik hizmetler ve arka plan işleri

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=ClientSecretCredential;" +
    "AuthTenantID=<tenant-id>;" +
    "AuthClientID=<client-id>;" +
    "AuthClientSecret=<client-secret>;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Gerekli Parametreler:

AuthTenantID: Azure kiracı kimliği
AuthClientID: Microsoft Entra Id'den uygulama (istemci) kimliği
AuthClientSecret: Microsoft Entra ID'den istemci sırrı

Sertifika tabanlı kimlik doğrulaması

En iyisi: Sertifika tabanlı kimlik doğrulaması gerektiren kurumsal uygulamalar

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=ClientCertificateCredential;" +
    "AuthTenantID=<tenant-id>;" +
    "AuthClientID=<client-id>;" +
    "AuthCertificatePath=C:\\certs\\mycert.pfx;" +
    "AuthCertificatePassword=<password>;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Gerekli Parametreler:

AuthTenantID: Azure kiracı kimliği
AuthClientID: Uygulama (istemci) kimliği
AuthCertificatePath: PFX/PKCS12 sertifika dosyasının yolu
AuthCertificatePassword: Sertifika parolası

Erişim belirteci kimlik doğrulaması

En iyisi: Özel kimlik doğrulama senaryoları

// Acquire token through your custom mechanism
string accessToken = await AcquireTokenFromCustomSourceAsync();

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AuthAccessToken;" +
    $"AuthAccessToken={accessToken};";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Kullanım örnekleri

Temel bağlantı ve sorgu

using Microsoft.Spark.Livy.AdoNet;

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine($"Connected! Server version: {connection.ServerVersion}");

// Execute a query
using var command = connection.CreateCommand();
command.CommandText = "SELECT * FROM employees LIMIT 10";

using var reader = await command.ExecuteReaderAsync();

// Print column names
for (int i = 0; i < reader.FieldCount; i++)
{
    Console.Write($"{reader.GetName(i)}\t");
}
Console.WriteLine();

// Print rows
while (await reader.ReadAsync())
{
    for (int i = 0; i < reader.FieldCount; i++)
    {
        Console.Write($"{reader.GetValue(i)}\t");
    }
    Console.WriteLine();
}

Parametreli sorgular

using var command = connection.CreateCommand();
command.CommandText = "SELECT * FROM orders WHERE order_date >= @startDate AND status = @status";

// Add parameters
command.Parameters.AddWithValue("@startDate", new DateTime(2024, 1, 1));
command.Parameters.AddWithValue("@status", "completed");

using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    Console.WriteLine($"Order: {reader["order_id"]}, Total: {reader["total"]:C}");
}

ExecuteScalar yöntemi, tek değerler için kullanılır.

using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) FROM customers";

var count = await command.ExecuteScalarAsync();
Console.WriteLine($"Total customers: {count}");

DML işlemleri için ExecuteNonQuery

// INSERT
using var insertCommand = connection.CreateCommand();
insertCommand.CommandText = @"
    INSERT INTO employees (id, name, department, salary)
    VALUES (100, 'John Doe', 'Engineering', 85000)";

int rowsAffected = await insertCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Inserted {rowsAffected} row(s)"
    : "The insert completed, but the driver didn't return an update count.");

// UPDATE
using var updateCommand = connection.CreateCommand();
updateCommand.CommandText = "UPDATE employees SET salary = 90000 WHERE id = 100";

rowsAffected = await updateCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Updated {rowsAffected} row(s)"
    : "The update completed, but the driver didn't return an update count.");

// DELETE
using var deleteCommand = connection.CreateCommand();
deleteCommand.CommandText = "DELETE FROM employees WHERE id = 100";

rowsAffected = await deleteCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Deleted {rowsAffected} row(s)"
    : "The delete completed, but the driver didn't return an update count.");

Büyük sonuç kümeleriyle çalışma

using var command = connection.CreateCommand();
command.CommandText = "SELECT * FROM large_table";

using var reader = await command.ExecuteReaderAsync();

int rowCount = 0;
while (await reader.ReadAsync())
{
    // Process each row
    ProcessRow(reader);
    rowCount++;

    if (rowCount % 10000 == 0)
    {
        Console.WriteLine($"Processed {rowCount} rows...");
    }
}

Console.WriteLine($"Total rows processed: {rowCount}");

Şema keşfi

// List all tables
using var showTablesCommand = connection.CreateCommand();
showTablesCommand.CommandText = "SHOW TABLES";

using var tablesReader = await showTablesCommand.ExecuteReaderAsync();
Console.WriteLine("Available tables:");
while (await tablesReader.ReadAsync())
{
    int tableNameOrdinal = tablesReader.GetOrdinal("tableName");
    Console.WriteLine($"  {tablesReader.GetString(tableNameOrdinal)}");
}

// Describe table structure
using var describeCommand = connection.CreateCommand();
describeCommand.CommandText = "DESCRIBE employees";

using var schemaReader = await describeCommand.ExecuteReaderAsync();
Console.WriteLine("\nTable structure for 'employees':");
while (await schemaReader.ReadAsync())
{
    Console.WriteLine($"  {schemaReader["col_name"]}: {schemaReader["data_type"]}");
}

// Show databases
using var dbCommand = connection.CreateCommand();
dbCommand.CommandText = "SHOW DATABASES";

using var dbReader = await dbCommand.ExecuteReaderAsync();
Console.WriteLine("\nAvailable databases:");
while (await dbReader.ReadAsync())
{
    Console.WriteLine($"  {dbReader.GetString(0)}");
}

LivyConnectionStringBuilder'ı kullanma

using Microsoft.Spark.Livy.AdoNet;

var builder = new LivyConnectionStringBuilder
{
    Server = "https://api.fabric.microsoft.com",
    SparkServerType = "Fabric",
    FabricWorkspaceID = "<workspace-id>",
    FabricLakehouseID = "<lakehouse-id>",
    AuthFlow = "AzureCli",
    ConnectionPoolingEnabled = true,
    MaxPoolSize = 10
};

using var connection = new LivyConnection(builder.ConnectionString);
await connection.OpenAsync();

DbProviderFactory'yi Kullanarak

using System.Data.Common;
using Microsoft.Spark.Livy.AdoNet;

// Register the provider factory (typically done at application startup)
DbProviderFactories.RegisterFactory("Microsoft.Spark.Livy.AdoNet", LivyProviderFactory.Instance);

// Create connection using factory
var factory = DbProviderFactories.GetFactory("Microsoft.Spark.Livy.AdoNet");

using var connection = factory.CreateConnection();
connection.ConnectionString = connectionString;

await connection.OpenAsync();

using var command = factory.CreateCommand();
command.Connection = connection;
command.CommandText = "SELECT * FROM employees LIMIT 5";

using var reader = await command.ExecuteReaderAsync();
// Process results...

Yüksek eşzamanlılık (HC) modu

Yüksek eşzamanlılık (HC) modu, .NET uygulamalarının her ADO.NET bağlantısı için ayrı bir klasik Spark oturumu sağlamadan eşzamanlı Spark SQL iş yüklerini çalıştırmasına yardımcı olur. Fabric, uyumlu bağlantıları sunucu tarafından yönetilen aynı Livy oturumunda barındırabilir ve her bağlantıya komutların yürütülmesi için yalıtılmış bir Read-Eval-Print Loop (REPL) sağlar.

Bu model, bağlantı başlatma süresini kısaltabilir, tekrarlanan Spark oturum provisioningini önleyebilir ve Fabric Spark kapasitesini daha verimli kullanabilir. Uygulamanız, DbConnection, OpenAsync, DbCommand, DbDataReader ve Close dahil olmak üzere standart ADO.NET API'lerini kullanmaya devam eder.

HC modu isteğe bağlıdır. Etkinleştirmezseniz, sürücü klasik Livy oturum yolunu kullanır.

HC ile klasik mod arasında seçim yapın

HC modunu şu durumlarda kullanın:

Bir ASP.NET servisi, bağlantıları açan ve Spark SQL'i çalıştıran eşzamanlı talepleri işler.
Bir arka plan hizmeti, zamanlanmış iş veya paralel veri işlem hattı, ADO.NET bağlantılarında ani artışlara neden olur.
Birden fazla bağlantı, aynı Fabric çalışma alanı ve göl evini hedef alır ve uyumlu Spark konfigürasyonları kullanır.
Bağlantı başlatma süresini ve Spark oturumlarının tekrar tekrar sağlanma süresini azaltmak önemlidir.
İş yükünüz, paylaşılmış, sunucu tarafından yönetilen Spark kapasitesini kullanabilir ve ifade yürütmesini REPL'den izole edebilir.

Klasik modu şu durumlarda kullanın:

Uygulamanız sadece bir veya birkaç uzun ömürlü bağlantı kullanır.
Her bağlantı, sıkı iş yükü veya kaynak izolasyonu için özel bir Spark oturumu gerektirir.
Bağlantılar, aynı temel oturumu paylaşmaması gereken birbirinden önemli ölçüde farklı Spark yapılandırmaları gerektirir.
Hedef çalışma alanı ve göl evi için Fabric Livy uç noktası HC modunu desteklemiyor.

HC bağlantıları nasıl çalışır

Uygulamanız Open veya OpenAsync çağrısı yaptığında ve uygun bir havuzlu bağlantı mevcut olmadığında, sürücü:

Fabric'ten HC oturumu ister.
Oturumun hazır duruma gelmesini, yapılandırılmış edinim zaman aşımı süresine kadar bekler.
ADO.NET bağlantısını atanan HC oturumuna ve REPL'e bağlar.
Komutları, sorguları, iptal taleplerini ve temizleme işlemlerini HC uç noktaları üzerinden yönlendirir.

Aynı anda kiralanan ayrı HC oturumları ayrı REPL'ler kullanır. Bir bağlantıdaki komutlar, o bağlantının HC oturumunu ve REPL'ini paylaşır.

İstemci tarafı havuzlama varsayılan olarak etkinleştirilmiştir. Uygun bir bağlantının kapatılması veya kullanımdan kaldırılması, fiziksel HC oturumunu ve REPL’i genellikle yeniden kullanılmak üzere işlem yerelindeki havuza geri döndürür; ancak atamayı uzak tarafta mutlaka serbest bırakmaz. Havuzlama devre dışı bırakıldığında, fiziksel bağlantının kapatılması HC temizliğini gerçekleştirir. Mantıksal bağlantıların hızlıca geri dönmesi için ifadeleri kullanmaya using devam edin.

HC modunu etkinleştir

HC modu isteğe bağlıdır. hcEnabled öğesini belirtmezseniz veya false olarak ayarlarsanız, sürücü klasik Livy oturum yolunu kullanır.

Bir HC oturumu edinmek için hcEnabled özelliğini true olarak ayarlayın:

hcEnabled=true;

Önemli

HC bağlantıları için, Server adına sürümsüz Fabric API ana makinesini kullanın. Sürücü, HC uç noktasını oluştururken varsayılan Fabric ve Livy API sürümlerini uygular.
Mülk isimleri büyük harf hassasiyetli değildir.

Oturum paketlemesini yapılandırın

HcSessionTag uyumlu HC oturumlarını altta yatan bir Livy oturumuna paketlemek için sunucu tarafı ipucu sağlar. Eşleşen bir etiket, aynı oturumda yer almayı garanti etmez.

Etiketi atlarsanız veya boş ya da sadece boşluk içeren bir değer verirseniz, sürücü bunu satın alma isteğinde göndermez. Etiketi çıkarmak, HC modunu veya servis tarafı paketlemeyi devre dışı bırakmaz. İlgili uygulama örnekleri veya iş yüklerinin paylaşılan kapasite için değerlendirilmesi gerektiğinde açık bir etiket belirleyin. Kararlı, hassas olmayan bir operasyonel etiket kullanın, örneğin reporting-service veya nightly-etl. Sırlar, erişim tokenları, kişisel veriler, müşteri tanımlayıcıları veya sorgu metni eklemeyin.

Spark yapılandırması da oturum uyumluluğunu etkiler. HC oturumu oluşturmak için izin verilen Spark ayarlarını sağlamak üzere HcConfOverrides kullanın:

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;AuthFlow=AzureCli;HcEnabled=true;HcConfOverrides="spark.executor.memory=8g;spark.executor.cores=4";

Birden fazla geçersiz bırakma için tüm HcConfOverrides değeri belirtin. Tırnak içine alınmamış bir noktalı virgül, başka bir dış bağlantı dizesi özelliği başlatır; HcConfOverrides ifadesini genişletmez. Ayrıştırıcı, tek veya çift tırnak içine alınmış değerleri kabul eder, tırnak içindeki noktalı virgül ve eşittir işaretlerini korur ve iki kez yazılmış eşleşen tırnak işaretlerini çözümler ('' veya ""). Özellik adlarının çevresindeki ve tırnak atılmayan değerlerin dış kenarlarındaki boşluk göz ardı edilir. Alıntılanmamış değerler içindeki boşluk ve tırnak değerleri içindeki tüm boşluklar korunur. Boş değerler ortam varsayılan ayarlarını geçersiz kılar ve son tekrarlanan özellik kazanır.

LivyConnectionStringBuilder öğesinin alıntı yapma işini de halletmesine izin verebilirsiniz:

var builder = new Microsoft.Spark.Livy.AdoNet.LivyConnectionStringBuilder
{
    Server = "https://api.fabric.microsoft.com",
    SparkServerType = "Fabric",
    FabricWorkspaceID = "<workspace-id>",
    FabricLakehouseID = "<lakehouse-id>",
    AuthFlow = "AzureCli",
    HcEnabled = true,
    HcConfOverrides = "spark.executor.memory=8g;spark.executor.cores=4"
};

string connectionString = builder.ConnectionString;

Bu örnekler Microsoft ADO.NET Driver sürüm 2.0.1 veya daha üzerini gerektirir. Bağlantı açmadan önce çalışma alanı ve göl evi tanımlayıcılarınızı ekleyin. Her iki geçersiz kılma da HC create-session isteğinde ayrı conf girişleri olarak gönderilir. Her geçersiz kılma, büyük/küçük harfe duyarlı şu anahtarlardan birini kullanmalıdır:

spark.sql.shuffle.partitions
spark.executor.memory
spark.executor.cores
spark.driver.memory
spark.sql.ansi.enabled
spark.sql.legacy.timeParserPolicy
spark.sql.session.timeZone
livy.rsc.client.connect.timeout
livy.rsc.server.idle-timeout

Hatalı tırnak işaretleri, bağlantı dizesi içeriği ayrıştırma hatasına dahil edilmeden reddedilir.

Kapasiteyi paylaşmak için tasarlanmış bağlantılar arasında tutarlı etiketler ve yapılandırma değerleri kullanın. Fabric, bir talebin mevcut bir oturumu kullanıp kullanamayacağını veya başka bir oturum gerektirip gerektirmediğini belirler.

Satın alma zamanlamasını yapılandırın

Sürücünün bir HC oturumunu ne kadar beklediğini kontrol etmek için aşağıdaki ayarları kullanın:

Parametre	Varsayılan	Geçerli giriş	Behavior
`hcAcquireTimeoutSeconds`	`300`	120'den 3.600 saniyeye kadar	HC oturumunun hazır olmasını beklemek için maksimum süre.
`hcAcquirePollingIntervalMs`	`1000`	50 ile 30.000 milisaniye arasında	Durum kontrolleri arasındaki aralık. Çalışma sırasında, sürücü değeri 100 ila 5.000 milisaniye aralığına sınırlar.

Çoğu iş yükü için varsayılan değerleri koruyun. Satın alma süresini yalnızca kapasite başlatma süresi düzenli olarak beş dakikadan uzun sürdüğünde artırın.

HC modunu bağlantı havuzu ile kullanın

HC modu ve ADO.NET bağlantı havuzu farklı katmanlara adres verir:

HC modu, sunucuda paylaşılan Fabric Spark kapasitesini ve Livy oturumlarını yönetir.
ADO.NET bağlantı havuzu, istemci uygulamasında sürücü tarafından yönetilen bağlantı kaynaklarını yeniden kullanır.

Her iki özelliği de etkinleştirebilirsiniz. Bağlantı havuzu, istemci tarafında tekrarlanan bağlantı kurulumunu azaltırken, HC modu sunucu tarafında tekrarlanan Spark oturumu sağlama işlemlerini azaltır. Gereksiz paralel iş yaratmak için büyük bir havuz kullanmak yerine uygulamanın beklenen eşzamanlılığı için bağlantı havuzunu boyutlandırın.

HC modunda, AutoReconnect=true durgun oturum hatasından sonra başarısız komutu şeffaf şekilde tekrar oynatmaz. Uygulama istisna alır ve işlemi tekrar denemenin güvenli olup olmadığına karar vermek zorundadır.

HC modunu devre dışı bırak

Yeni bağlantılarda klasik modu kullanmak için HcEnabled öğesini bağlantı dizesinden kaldırın veya bunu false olarak ayarlayın:

HcEnabled=false

Bu değişiklik yeni bağlantıları etkiliyor ve mevcut havuza alınmış HC oturumlarını boşaltmıyor. Mantıksal bağlantıları normal şekilde kapatın veya sonlandırın; uygun fiziksel oturumlar, kullanımdan kaldırılıncaya kadar istemci havuzunda kalabilir.

ADO.NET sınırlamaları

İşlemler desteklenmiyor.
Komutlar yalnızca metin komut modunu destekler. Kayıtlı prosedür ve tabloya doğrudan komut modları desteklenmez.
Prepare hiçbir şey yapmaz.
Bir komut bir i'lim içermelidir; çoklu ifadeli komut metni reddedilir.
Eşzamanlı iş yükleri için ayrı ve aynı anda açık bağlantılar kullanın. Bir bağlantıdaki komutlar oturumunu ve REPL'i paylaşır.

Veri türü eşlemesi

Sürücü Spark SQL veri türlerini .NET türleriyle eşler:

Spark SQL Türü	.NET Türü	DbType
BOOLEAN	`bool`	Boolean
TINYINT	`sbyte`	SByte
SMALLINT (Küçük Tamsayı)	`short`	Int16
INT	`int`	Int32
BIGINT	`long`	Int64
FLOAT	`float`	Single
ÇİFT	`double`	Double
ONDALıK(p,s)	`decimal`	Ondalık
STRING	`string`	Dize
VARCHAR(n)	`string`	Dize
CHAR(n)	`string`	Dize
BINARY	`byte[]`	İkilik
DATE	`DateTime`	Tarih
TIMESTAMP	`DateTime`	Tarih Saat
DIZI<T>	`string`	Nesne
MAP<K,V>	`string`	Nesne
Yapı	`string`	Nesne

Karmaşık türlerle çalışma

HC sonuç yolu, yerel iç içe ARRAY, MAP veya STRUCT değerlerini JSON olarak güvenilir şekilde serileştirmez. Spark SQL'de, karmaşık değerleri seri durumdan çıkarmadan önce JSON dizelerine dönüştürün:

using System.Text.Json;
using System.Collections.Generic;

using var command = connection.CreateCommand();
command.CommandText = """
    SELECT
        to_json(array_column) AS array_json,
        to_json(map_column) AS map_json,
        to_json(struct_column) AS struct_json
    FROM complex_table
    LIMIT 1
    """;

using var reader = await command.ExecuteReaderAsync();
if (await reader.ReadAsync())
{
    string arrayJson = reader.GetString(0);
    string mapJson = reader.GetString(1);
    string structJson = reader.GetString(2);

    var array = JsonSerializer.Deserialize<int[]>(arrayJson);
    var map = JsonSerializer.Deserialize<Dictionary<string, string>>(mapJson);
}

Sorun giderme

Bu bölüm, Microsoft ADO.NET Driver for Fabric Data Engineering'i kullanırken karşılaşabileceğiniz yaygın sorunları çözmek için rehberlik sağlar.

Yaygın sorunlar

Aşağıdaki bölümlerde yaygın sorunlar ve çözümleri açıklanmaktadır:

Bağlantı hataları

Sorun: Fabric'e bağlanamıyor

Çözümler:

FabricWorkspaceID ve FabricLakehouseID doğru GUID'ler olduğunu doğrulayın.
Azure CLI kimlik doğrulamayı denetleyin: az account show
Uygun Fabric çalışma alanı izinlerine sahip olduğunuzdan emin olun
Ağ bağlantısını doğrula api.fabric.microsoft.com

Kimlik doğrulama hataları

Sorun: Azure CLI ile kimlik doğrulaması başarısız oluyor

Çözümler:

Kimlik bilgilerini yenilemek için komutunu çalıştırın az login
Doğru kiracıyı doğrulayın: az account set --subscription <subscription-id>
Belirteç geçerliliğini denetleyin: az account get-access-token --resource https://api.fabric.microsoft.com

Sorgu zaman aşımları

Sorun: Büyük tablolarda sorguların zaman aşımına uğraması

Çözümler:

Bildirim süresini artırın: LivyStatementTimeoutSeconds=1200.
Geliştirme sırasında sonuç boyutunu kısıtlamak için yan tümcesi kullanın LIMIT
Spark kümesinin yeterli kaynağa sahip olduğundan emin olun

Bağlantı veya HC edinme zaman aşımı

Sorun: Bağlantı havuzundan bir bağlantı veya bir HC oturumu beklenirken bağlantı zaman aşımına uğruyor

Çözümler:

İstemci havuzu bekleme süresi ve HTTP bağlantısının kurulması için HttpConnectionTimeoutInSeconds öğesini inceleyin.
HC edinimi için, hcAcquireTimeoutSeconds değerini desteklenen 120 ila 3.600 saniye aralığı içinde artırın.
Ağ Yapısı kapasitesi uygunluğunu kontrol et
Çalışma alanının oturum sınırlarına ulaşmadığını doğrulama

Log kaydını etkinleştir

Sorunları giderirken, ayrıntılı kayıt tutma temel nedeni belirlemenize yardımcı olabilir. Logu bağlantı dizesi üzerinden yapılandırın:

Bağlantı dizesi aracılığıyla ayrıntılı günlüğe kaydı etkinleştirmek için:

LogLevel=Debug;LogFilePath=<path-to-log-file>

LogFilePath veya genel bir günlük kaydı yapılandırması ayarlamazsanız, sürücü günlükleri Windows'ta %LOCALAPPDATA%\FabricSparkAdoNet\Logs altında yazar.

Log seviyeleri:

Trace: En ayrıntılı, tüm API çağrılarını içerir
Debug: Ayrıntılı hata ayıklama bilgileri
Information: Genel bilgiler (varsayılan)
Warning: Yalnızca uyarılar
Error: Sadece hatalar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-10-01

Microsoft ADO.NET sürücüsü Microsoft Fabric Data Engineering için

Temel özellikler

Önkoşullar

İndirme, ekleme, başvuru ve doğrulama

NuGet paketini indirme

Projenizde NuGet paketine başvurma

Yüklemeyi doğrulama

Hızlı başlangıç örneği

Bağlantı dizesi biçimi

Temel biçim

Gerekli parametreler

İsteğe bağlı parametreler

Bağlantı ayarları

Bağlantı havuzu ayarları

Yüksek eşzamanlılık ayarları

Kayıt ayarları

Örnek bağlantı dizeleri

Temel bağlantı (Azure CLI kimlik doğrulaması)

Yüksek eşzamanlı bağlantı

Bağlantı havuzu seçenekleriyle

Otomatik yeniden bağlanma ve günlüğe kaydetme ile

Kimlik Doğrulaması

Kimlik doğrulama yöntemleri

Azure CLI kimlik doğrulaması

Etkileşimli tarayıcı kimlik doğrulaması

İstemci Kimlik Bilgileri (Hizmet Sorumlusu) Kimlik Doğrulaması

Sertifika tabanlı kimlik doğrulaması

Erişim belirteci kimlik doğrulaması

Kullanım örnekleri

Temel bağlantı ve sorgu

Parametreli sorgular

ExecuteScalar yöntemi, tek değerler için kullanılır.

DML işlemleri için ExecuteNonQuery

Büyük sonuç kümeleriyle çalışma

Şema keşfi

LivyConnectionStringBuilder'ı kullanma

DbProviderFactory'yi Kullanarak

Yüksek eşzamanlılık (HC) modu

HC ile klasik mod arasında seçim yapın

HC bağlantıları nasıl çalışır

HC modunu etkinleştir

Oturum paketlemesini yapılandırın

Satın alma zamanlamasını yapılandırın

HC modunu bağlantı havuzu ile kullanın

HC modunu devre dışı bırak

ADO.NET sınırlamaları

Veri türü eşlemesi

Karmaşık türlerle çalışma

Sorun giderme

Yaygın sorunlar

Bağlantı hataları

Kimlik doğrulama hataları

Sorgu zaman aşımları

Bağlantı veya HC edinme zaman aşımı

Log kaydını etkinleştir

İlgili içerik

Geri Bildirim

Ek kaynaklar