Microsoft ADO.NET-Treiber für Microsoft Fabric Data Engineering

ADO.NET ist eine weit verbreitete Datenzugriffstechnologie im .NET-Ökosystem, mit der Anwendungen eine Verbindung mit Daten aus Datenbanken und Big Data-Plattformen herstellen und damit arbeiten können.

Der Microsoft ADO.NET Driver for Fabric Data Engineering ermöglicht es Ihnen, Spark-Workloads in Fabric mit der Zuverlässigkeit und Einfachheit von Standard-ADO.NET-Mustern zu verbinden, abzufragen und zu verwalten. Der auf den Livy-APIs von Fabric basierende Treiber bietet sichere und flexible Spark-SQL-Konnektivität zu Ihren .NET-Anwendungen mittels vertrauter DbConnection, DbCommand, und DbDataReader Abstraktionen.

Wichtigste Funktionen

• ADO.NET-APIs: Vertraute DbConnection, DbCommand, DbDataReader, DbParameter, und DbProviderFactory Abstraktionen für Spark SQL-Konnektivität
• Microsoft Entra ID-Authentifizierung: Mehrere Authentifizierungsflüsse wie Azure CLI, interaktiver Browser, Clientanmeldeinformationen, zertifikatbasierte und Zugriffstokenauthentifizierung
• Spark SQL Native Query Support: Direkte Ausführung von Spark SQL-Anweisungen mit parametrisierten Abfragen
• Umfassende Unterstützung für Datentypen: Unterstützung für alle Spark SQL-Datentypen einschließlich komplexer Typen (ARRAY, MAP, STRUCT)
• Verbindungspooling: Integrierte Verbindungspoolverwaltung für verbesserte Leistung
• Sitzungswiederverwendung: Effiziente Spark-Sitzungsverwaltung zur Reduzierung der Startlatenz
• Sitzungen mit hoher Parallelität: Nutzen Sie die gemeinsame Fabric Livy-Kapazität mit separaten REPLs für gleichzeitig zugewiesene HC-Sitzungen
• Async Prefetch: Asynchrones Vorabrufen von Hintergrunddaten für verbesserte Leistung bei großen Ergebnis-Sets
• Automatische Wiederverbindung: Wiederherstellung klassischer Sitzungen nach Verbindungsfehlern; HC-Fehler werden für anwendungsgesteuerte Wiederholungsversuche verfügbar gemacht

Voraussetzungen

Bevor Sie den Microsoft ADO.NET Driver für Fabric Data Engineering verwenden, stellen Sie sicher, dass Sie Folgendes besitzen:

• .NET Runtime: .NET 8.0 oder höher
• Fabric Access: Zugang zu einem Fabric-Arbeitsbereich mit Data-Engineering-Funktionen
• Azure Entra ID-Anmeldeinformationen: Geeignete Anmeldeinformationen für die Authentifizierung
• Arbeitsbereichs- und Lakehouse-IDs: GUID-IDs für den Fabric-Arbeitsbereich und das Lakehouse
• Azure CLI (optional): Erforderlich für die Azure CLI-Authentifizierungsmethode

Herunterladen, Einschließen, Verweisen und Überprüfen

NuGet-Paket herunterladen

• Laden Sie den Microsoft ADO.NET Driver für Fabric Data Engineering herunter (zip)
• Laden Sie den Microsoft ADO.NET Driver für Fabric Data Engineering (tar) herunter

Referenz nuGet-Paket in Ihrem Projekt

Fügen Sie das heruntergeladene NuGet-Paket in Ihr Projekt ein, und fügen Sie ihrer Projektdatei einen Verweis auf das Paket hinzu:

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

Überprüfen der Installation

Überprüfen Sie nach der Aufnahme und Referenz, ob das Paket in Ihrem Projekt verfügbar ist:

using Microsoft.Spark.Livy.AdoNet;

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

Schnellstartbeispiel

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

Format der Verbindungszeichenfolge

Standardformat

Der Microsoft ADO.NET-Treiber verwendet standardmäßiges ADO.NET Verbindungszeichenfolgenformat:

Parameter1=Value1;Parameter2=Value2;...

Erforderliche Parameter

Optionale Parameter

Verbindungseinstellungen

Verbindungspooleinstellungen

Hohe Parallelitätseinstellungen

Logging-Einstellungen

Treiberübergreifende Aliase: Der Treiber akzeptiert neben systemeigenen ADO.NET-Namen auch JDBC- und ODBC-Property-Namen (z. B. WorkspaceId entspricht FabricWorkspaceID, LakehouseId entspricht FabricLakehouseID). Alle Eigenschaftsnamen sind groß- und kleinschreibungsunabhängig.

Exemplarische Verbindungszeichenfolgen

Grundlegende Verbindung (Azure CLI-Authentifizierung)

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

Verbindung mit hoher Parallelität

Hohe Parallelität wird für Microsoft Fabric-Verbindungen unterstützt. Setze HcEnabled=true; die Standard-ADO.NET-Verbindungs- und Befehls-APIs bleiben unverändert. Verwenden Sie den unversionierten Fabric API-Host für Server; der Treiber verwendet FabricVersion=v1 und LivyApiVersion=2023-12-01 standardmäßig beim Erstellen des HC-Endpunkts.

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

Eine vollständige Anleitung zur Konfiguration finden Sie im Abschnitt „High-Concurrency-(HC)-Modus“.

Mit Verbindungspoolingoptionen

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

Mit automatischer Wiederverbindung und Protokollierung

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

Authentifizierung

Der Microsoft ADO.NET Driver unterstützt mehrere Authentifizierungsmethoden über Microsoft Entra ID (früher Azure Active Directory). Die Authentifizierung wird mithilfe des AuthFlow Parameters in der Verbindungszeichenfolge konfiguriert.

Authentifizierungsmethoden

Azure CLI-Authentifizierung

Am besten geeignet für: Entwicklung und Tests

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 installiert: az --version
• Angemeldet: az login

Interaktive Browserauthentifizierung

Am besten geeignet für: Benutzerorientierte Anwendungen

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

Verhalten:

• Öffnet ein Browserfenster für die Benutzerauthentifizierung.
• Anmeldeinformationen werden für nachfolgende Verbindungen zwischengespeichert.

Authentifizierung mit Client-Anmeldeinformationen (Dienstprinzipal)

Am besten geeignet für: Automatisierte Dienste und Hintergrundaufträge

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();

Erforderliche Parameter:

• AuthTenantID: Azure-Mandanten-ID
• AuthClientID: Anwendungs-ID (Client-ID) von Microsoft Entra ID
• AuthClientSecret: Geheimer Clientschlüssel von Microsoft Entra ID

Zertifikatbasierte Authentifizierung

Am besten geeignet für: Unternehmensanwendungen, die zertifikatbasierte Authentifizierung erfordern

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();

Erforderliche Parameter:

• AuthTenantID: Azure-Mandanten-ID
• AuthClientID: Anwendungs-ID (Client-ID)
• AuthCertificatePath: Pfad zur PFX/PKCS12-Zertifikatdatei
• AuthCertificatePassword: Zertifikatkennwort

Zugriffstokenauthentifizierung

Am besten geeignet für: Benutzerdefinierte Authentifizierungsszenarien

// 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();

Verwendungsbeispiele

Grundlegende Verbindung und Abfrage

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

Parametrisierte Abfragen

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 für Einzelwerte

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

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

ExecuteNonQuery für DML-Vorgänge

// 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.");

Arbeiten mit großen Ergebnismengen

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

Schema-Ermittlung

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

Verwenden von LivyConnectionStringBuilder

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();

Verwenden von DbProviderFactory

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...

Hoch-Nebenläufigkeit (HC) Modus

Der High-Concurrency (HC)-Modus hilft .NET-Anwendungen, gleichzeitige Spark SQL-Workloads auszuführen, ohne für jede ADONET-Verbindung eine separate klassische Spark-Sitzung bereitzustellen. Fabric kann kompatible Verbindungen in derselben serververwalteten Livy-Sitzung platzieren und jeder Verbindung eine isolierte Read-Eval-Print Loop (REPL) für die Ausführung der Anweisungen bereitstellen.

Dieses Modell kann die Startzeit der Verbindung verkürzen, wiederholte Spark-Session-Provisionierung vermeiden und die Fabric Spark-Kapazität effizienter nutzen. Ihre Anwendung verwendet weiterhin Standard-ADO.NET-APIs, darunter DbConnection, DbCommand, DbDataReader, , OpenAsyncund Close.

Der HC-Modus ist opt-in. Wenn du es nicht aktivierst, verwendet der Treiber den klassischen Livy-Sitzungspfad.

Wähle zwischen HC und Classic-Modus

Benutze den HC-Modus wenn:

• Ein ASP.NET-Dienst verarbeitet gleichzeitige Anfragen, die Verbindungen öffnen und Spark SQL ausführen.
• Ein Worker-Service, ein geplanter Auftrag oder eine parallele Datenpipeline erzeugt Bursts von ADO.NET-Verbindungen.
• Mehrere Verbindungen zielen auf denselben Fabric-Arbeitsplatz und das Lakehouse ab und verwenden kompatible Spark-Konfigurationen.
• Die Verkürzung der Verbindungsstartzeit und der wiederholten Spark-Session-Bereitstellung ist wichtig.
• Ihre Arbeitslast kann gemeinsame, serververwaltete Spark-Kapazität nutzen, während die Ausführung von Anweisungen durch REPL isoliert bleibt.

Nutze den klassischen Modus, wenn:

• Ihre Anwendung verwendet nur eine oder wenige langlebige Verbindungen.
• Jede Verbindung benötigt eine dedizierte Spark-Session für strikte Workload- oder Ressourcenisolation.
• Verbindungen erfordern wesentlich unterschiedliche Spark-Konfigurationen, die keine zugrundeliegende Sitzung teilen sollten.
• Der Fabric Livy-Endpunkt für den Zielarbeitsbereich und das Lakehouse unterstützt den HC-Modus nicht.

So funktionieren HC-Verbindungen

Wenn Ihre Anwendung Open oder OpenAsync aufruft und keine kompatible gepoolte Verbindung verfügbar ist, geht der Treiber wie folgt vor:

1. Fordert eine HC-Sitzung bei Fabric an.
2. Wartet, bis die Sitzung bereit ist, bis zur konfigurierten Erfassungszeit.
3. Verbindet die ADO.NET-Verbindung mit der zugewiesenen HC-Sitzung und REPL.
4. Leitet Befehle, Abfragen, Abbruchanfragen und Bereinigungsvorgänge über die HC-Endpunkte weiter.

Separate, gleichzeitig vermietete HC-Sitzungen verwenden separate REPLs. Befehle innerhalb derselben Verbindung nutzen gemeinsam deren HC-Sitzung und die REPL.

Client-seitiges Pooling ist standardmäßig aktiviert. Das Schließen oder Entsorgen einer berechtigten Verbindung führt normalerweise dazu, dass die physische HC-Sitzung und REPL an den prozesslokalen Pool zur Wiederverwendung zurückgegeben werden; die Zuweisung wird nicht unbedingt remote freigegeben. Bei deaktiviertem Pooling erfolgt beim Schließen der physischen Verbindung die HC-Bereinigung. Verwenden Sie weiterhin using Anweisungen, damit logische Zusammenhänge umgehend wiederhergestellt werden.

HC-Modus aktivieren

Der HC-Modus ist opt-in. Wenn Sie hcEnabled weglassen oder auf „false“ setzen, verwendet der Treiber den klassischen Livy-Sitzungspfad.

Setzen Sie die Eigenschaft hcEnabled auf true, um eine HC-Sitzung zu starten:

hcEnabled=true;

Session Packing konfigurieren

HcSessionTag bietet einen serverseitigen Hinweis zum Packen kompatibler HC-Sitzungen in eine zugrundeliegende Livy-Sitzung. Ein übereinstimmendes Tag garantiert keine Zuordnung zur selben zugrunde liegenden Sitzung.

Wenn du den Tag weglässt oder einen leeren oder nur aus Leerraum bestehenden Wert angibst, sendet der Treiber ihn nicht in der Anforderung zum Abrufen. Das Weglassen des Tags deaktiviert weder den HC-Modus noch das serverseitige Packen. Setzen Sie ein explizites Tag, wenn verwandte Anwendungsinstanzen oder Workloads für geteilte Kapazitäten berücksichtigt werden sollten. Verwenden Sie ein stabiles, nicht sensibles Operationslabel, wie reporting-service oder nightly-etl. Fügen Sie keine Geheimnisse, Zugriffstoken, persönliche Daten, Kundenkennungen oder Anfragetexte hinzu.

Auch die Spark-Konfiguration beeinflusst die Sitzungskompatibilität. Verwenden Sie HcConfOverrides, um zugelassene Spark-Einstellungen für die Erstellung von HC-Sitzungen bereitzustellen:

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

Bei mehreren Überschreibungen setzen Sie den gesamten Wert HcConfOverrides in Anführungszeichen. Ein nicht in Anführungszeichen gesetztes Semikolon beginnt eine weitere Eigenschaft der äußeren Verbindungszeichenfolge; es erweitert HcConfOverrides nicht. Der Parser akzeptiert Werte in einfachen oder doppelten Anführungszeichen, behält Semikolons und Gleichheitszeichen innerhalb von Werten in Anführungszeichen bei und dekodiert verdoppelte passende Anführungszeichen ('' oder ""). Weißraum um Immobiliennamen und an den äußeren Rändern unangeführter Werte wird ignoriert. Weißraum innerhalb unangeführter Werte und alle Leerräume innerhalb der Anführungswerte bleiben erhalten. Leere Werte überschreiben die Umgebungsstandardwerte, und die letzte doppelte Eigenschaft gewinnt.

Sie können auch LivyConnectionStringBuilder die Angebotserstellung überlassen:

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;

Diese Beispiele erfordern Microsoft ADO.NET Driver Version 2.0.1 oder neuer. Füge vor dem Öffnen einer Verbindung deine Workspace- und Lakehouse-IDs hinzu. Beide Überschreibungen werden in der HC-Create-Session-Anfrage als separate conf-Einträge gesendet. Jede Überschreibung muss einen dieser die Groß-/Kleinschreibung beachtenden Schlüssel verwenden:

• 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

Fehlgeformte Anführungszeichen werden abgelehnt, ohne den Inhalt der Verbindungsstrings in den Parsefehler einzubeziehen.

Verwenden Sie konsistente Tags und Konfigurationswerte über Verbindungen hinweg, die die Kapazität teilen sollen. Fabric bestimmt, ob eine Anfrage eine bestehende Sitzung verwenden kann oder eine weitere Sitzung benötigt.

Erwerbszeitpunkt konfigurieren

Verwenden Sie die folgenden Einstellungen, um zu steuern, wie lange der Fahrer auf eine HC-Sitzung wartet:

Für die meisten Arbeitslasten sollten Sie die Standardwerte behalten. Erhöhen Sie die Akquisitionszeit nur, wenn der Kapazitätsstart regelmäßig länger als fünf Minuten dauert.

Verwenden Sie den HC-Modus mit Verbindungspooling

HC-Modus und ADO.NET-Verbindungspooling adressieren verschiedene Schichten:

• Der HC-Modus verwaltet die geteilte Fabric Spark-Kapazität und Livy-Sitzungen auf dem Server.
• ADO.NET-Verbindungspooling verwendet treiberverwaltete Verbindungsressourcen in der Client-Anwendung.

Du kannst beide Funktionen aktivieren. Verbindungspooling reduziert den wiederholten clientseitigen Verbindungsaufbau, während der HC-Modus die wiederholte serverseitige Bereitstellung von Spark-Sitzungen reduziert. Passen Sie die Größe des Verbindungspools an die erwartete Parallelität der Anwendung an, anstatt einen großen Pool zu verwenden, der unnötige Parallelverarbeitung erzeugt.

Im HC-Modus wiederholt AutoReconnect=true einen fehlgeschlagenen Befehl nach einem Stale-Session-Fehler nicht automatisch im Hintergrund. Die Anwendung erhält die Ausnahme und muss entscheiden, ob ein erneuter Versuch der Operation sicher ist.

HC-Modus deaktivieren

Um den klassischen Modus für neue Verbindungen zu verwenden, entfernen Sie HcEnabled aus der Verbindungszeichenfolge oder setzen Sie den Wert auf false:

HcEnabled=false

Die Änderung wirkt sich auf neue Verbindungen aus und spült nicht bestehende, gepoolte HC-Sitzungen aus. Schließen Sie logische Verbindungen ordnungsgemäß; geeignete physische Sitzungen können im Client-Pool verbleiben, bis sie ausgemustert werden.

ADO.NET Einschränkungen

• Transaktionen werden nicht unterstützt.
• Befehle unterstützen nur den Textbefehlsmodus. Die Befehlsmodi „Stored Procedure“ und „Table Direct“ werden nicht unterstützt.
• Mit Prepare passiert nichts.
• Ein Befehl muss eine Anweisung enthalten; der Befehlstext mit mehreren Anweisungen wird abgelehnt.
• Verwenden Sie separate, gleichzeitig offene Verbindungen für gleichzeitige Arbeitslasten. Befehle über dieselbe Verbindung nutzen dieselbe Sitzung und dieselbe REPL.

Datentypzuordnung

Der Treiber ordnet Spark SQL-Datentypen .NET-Typen zu:

Arbeiten mit komplexen Typen

Der HC-Ergebnispfad serialisiert nicht zuverlässig native verschachtelte ARRAY-, MAP- oder STRUCT-Werte als JSON. Wandle komplexe Werte in Spark SQL vor der Deserialisierung in JSON-Zeichenfolgen um:

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

Problembehandlung

Dieser Abschnitt bietet Anleitungen zur Lösung häufiger Probleme, die bei der Nutzung des Microsoft ADO.NET Driver for Fabric Data Engineering auftreten könnten.

Häufig auftretende Probleme

In den folgenden Abschnitten werden allgemeine Probleme und deren Lösungen beschrieben:

Verbindungsfehler

Problem: Keine Verbindung zu Fabric

Lösungen:

1. Überprüfen Sie, ob FabricWorkspaceID und FabricLakehouseID korrekte GUIDs sind.
2. Überprüfen sie die Azure CLI-Authentifizierung: az account show
3. Stellen Sie sicher, dass Sie über entsprechende Fabric-Arbeitsbereichsberechtigungen verfügen.
4. Überprüfen der Netzwerkkonnektivität mit api.fabric.microsoft.com

Authentifizierungsfehler

Problem: Die Authentifizierung schlägt mit Azure CLI fehl

Lösungen:

• Ausführen az login zum Aktualisieren von Anmeldeinformationen
• Überprüfen Sie, ob es sich um den richtigen Mandanten handelt: az account set --subscription <subscription-id>
• Gültigkeit des Tokens überprüfen: az account get-access-token --resource https://api.fabric.microsoft.com

Abfrage-Timeouts

Problem: Abfragen, die bei großen Tabellen eine Zeitüberschreitung haben

Lösungen:

• Aussage-Timeout erhöhen: LivyStatementTimeoutSeconds=1200.
• Verwenden einer LIMIT Klausel zum Einschränken der Ergebnisgröße während der Entwicklung
• Sicherstellen, dass Spark-Cluster über ausreichende Ressourcen verfügt

Verbindung oder HC-Akquisitionszeitbegrenzung

Problem: Eine Verbindung fällt ab, während man auf eine gepoolte Verbindung oder eine HC-Sitzung wartet.

Lösungen:

• Für die Wartezeit im Client-Pool und HTTP-Verbindungsaufbau, überprüfe HttpConnectionTimeoutInSeconds.
• Für die HC-Erfassung erhöhen Sie hcAcquireTimeoutSeconds innerhalb des unterstützten Bereichs von 120 bis 3.600 Sekunden.
• Überprüfen der Verfügbarkeit der Fabric-Kapazität
• Überprüfen, ob der Arbeitsbereich keine Sitzungsgrenzwerte erreicht hat

Aktivieren der Protokollierung

Bei der Fehlersuche kann eine detaillierte Protokollierung helfen, die Ursache zu identifizieren. Konfigurieren Sie das Logging über den Verbindungszeichenfolge:

So aktivieren Sie die detaillierte Protokollierung über Verbindungszeichenfolge.

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

Wenn Sie weder LogFilePath noch eine globale Logging-Konfiguration festlegen, schreibt der Treiber die Protokolle unter Windows unter %LOCALAPPDATA%\FabricSparkAdoNet\Logs.

Protokollebenen:

• Trace: Am ausführlichsten, umfasst alle API-Aufrufe.
• Debug: Detaillierte Debuginformationen
• Information: Allgemeine Informationen (Standard)
• Warning: Nur Warnungen
• Error: Nur Fehler

Verwandte Inhalte

• Apache-Spark-Runtimes in Fabric
• Fabric Runtime 1.3
• Was ist die Livy-API für Data Engineering
• Microsoft JDBC-Treiber für Fabric Data Engineering
• Microsoft ODBC-Treiber für Fabric Data Engineering