Microsoft ADO.NET-driver voor Microsoft Fabric Data Engineering

ADO.NET is een veelgebruikte technologie voor gegevenstoegang in het .NET-ecosysteem waarmee toepassingen verbinding kunnen maken met en kunnen werken met gegevens uit databases en big data-platforms.

De Microsoft ADO.NET Driver for Fabric Data Engineering stelt je in staat Spark-workloads in Fabric te verbinden, op te vragen en te beheren met de betrouwbaarheid en eenvoud van standaard ADO.NET-patronen. Gebouwd op Fabric's Livy-API's, biedt de driver veilige en flexibele Spark SQL-connectiviteit naar je .NET-applicaties via bekende DbConnection, DbCommand, en DbDataReader abstracties.

Belangrijkste kenmerken

• ADO.NET API's: Vertrouwde DbConnection, DbCommand, , DbDataReader, DbParameteren DbProviderFactory abstracties voor Spark SQL-connectiviteit
• Microsoft Entra ID-verificatie: meerdere verificatiestromen, waaronder Azure CLI, interactieve browser, clientreferenties, verificatie op basis van certificaten en toegangstokenverificatie
• Ondersteuning voor systeemeigen Spark SQL-query's: Directe uitvoering van Spark SQL-instructies met geparameteriseerde query's
• Uitgebreide ondersteuning voor gegevenstypen: ondersteuning voor alle Spark SQL-gegevenstypen, waaronder complexe typen (ARRAY, MAP, STRUCT)
• Groepsgewijze verbindingen: ingebouwd beheer van verbindingsgroepen voor verbeterde prestaties
• Sessie opnieuw gebruiken: Efficiënt Spark-sessiebeheer om de opstartlatentie te verminderen
• Sessies met hoge gelijktijdigheid: Kies voor gedeelde Fabric Livy-capaciteit met afzonderlijke REPL's voor gelijktijdig toegewezen HC-sessies
• Asynchrone prefetch: achtergrondgegevens laden voor verbeterde prestaties met grote resultatensets
• Automatisch opnieuw verbinden: Herstel van klassieke sessies na verbindingsfouten; HC-fouten worden doorgegeven voor door de applicatie aangestuurde nieuwe pogingen

Vereiste voorwaarden

Voordat je de Microsoft ADO.NET Driver for Fabric Data Engineering gebruikt, zorg ervoor dat je:

• .NET Runtime: .NET 8.0 of hoger
• Fabric Access: Toegang tot een Fabric-werkruimte met Data Engineering-mogelijkheden
• Referenties voor Azure Entra ID: juiste referenties voor authenticatie
• Werkruimte- en Lakehouse-id's: GUID-id's voor uw Fabric-werkruimte en Lakehouse
• Azure CLI (optioneel): vereist voor azure CLI-verificatiemethode

Downloaden, opnemen, verwijzen en verifiëren

NuGet-pakket downloaden

• Download Microsoft ADO.NET Driver for Fabric Data Engineering (zip)
• Download Microsoft ADO.NET Driver for Fabric Data Engineering (tar)

Neem het NuGet-pakket op in uw project

Neem het gedownloade NuGet-pakket op in uw project en voeg een verwijzing van het pakket toe aan uw projectbestand:

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

Installatie controleren

Controleer na opname en verwijzing of het pakket beschikbaar is in uw project:

using Microsoft.Spark.Livy.AdoNet;

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

Snelstartvoorbeeld

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

Indeling van verbindingstekenreeks

Basisindeling

Het Microsoft ADO.NET-stuurprogramma maakt gebruik van de standaardindeling voor ADO.NET verbindingsreeks:

Parameter1=Value1;Parameter2=Value2;...

Benodigde parameters

Optionele parameters

Verbindingsinstellingen

Instellingen voor verbindingsgroep

Hoge gelijktijdigheidsinstellingen

Instellingen voor logboekregistratie

Aliassen voor meerdere stuurprogramma's: Het stuurprogramma accepteert naast systeemeigen ADO.NET namen ook namen van JDBC- en ODBC-eigenschappen (bijvoorbeeld WorkspaceId wordt toegewezen aan FabricWorkspaceID, en LakehouseId wordt toegewezen aan FabricLakehouseID). Alle eigenschapsnamen zijn niet-hoofdlettergevoelig.

Voorbeeld van verbindingsreeksen

Basisverbinding (Azure CLI-verificatie)

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

Veel gelijktijdige verbindingen

Hoge gelijktijdigheid is beschikbaar voor Microsoft Fabric-verbindingen. Stel HcEnabled=true; de standaard ADO.NET-verbinding- en commando-API's blijven ongewijzigd. Gebruik de niet-geversioneerde Fabric API-hostnaam voor Server; de driver gebruikt standaard FabricVersion=v1 en LivyApiVersion=2023-12-01 bij het opbouwen van het HC-eindpunt.

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

Voor volledige configuratierichtlijnen, zie de sectie High-Concurrency (HC) Modus .

Met opties voor groepsgewijze verbindingen

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

Met automatisch opnieuw verbinden en logboekregistratie

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

Authentication

Het Microsoft ADO.NET-stuurprogramma ondersteunt meerdere verificatiemethoden via Microsoft Entra ID (voorheen Azure Active Directory). Verificatie wordt geconfigureerd met behulp van de AuthFlow parameter in de verbindingsreeks.

Verificatiemethoden

Azure CLI-verificatie

Geschikt voor: Ontwikkeling en testen

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

vereisten:

• Azure CLI geïnstalleerd: az --version
• Ingelogd: az login

Interactieve browserverificatie

Geschikt voor: gebruikersgerichte toepassingen

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

Gedrag:

• Hiermee opent u een browservenster voor gebruikersverificatie
• Referenties worden in de cache opgeslagen voor volgende verbindingen

Verificatie van clientreferenties (service-principal)

Geschikt voor: Geautomatiseerde services en achtergrondtaken

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

Vereiste parameters:

• AuthTenantID: Azure-tenant-id
• AuthClientID: Toepassings-ID (client) van Microsoft Entra ID
• AuthClientSecret: Clientgeheim van Microsoft Entra-id

Verificatie op basis van certificaat

Geschikt voor: Bedrijfstoepassingen waarvoor verificatie op basis van certificaten is vereist

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

Vereiste parameters:

• AuthTenantID: Azure-tenant-id
• AuthClientID: Applicatie-ID (client)
• AuthCertificatePath: Pad naar PFX-/PKCS12-certificaatbestand
• AuthCertificatePassword: Certificaatwachtwoord

Verificatie van toegangstokens

Geschikt voor: Scenario's voor aangepaste verificatie

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

Voorbeelden van gebruik

Eenvoudige verbinding en opvraging

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

Geparameteriseerde query's

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 voor enkele waarden

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

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

ExecuteNonQuery voor DML-bewerkingen

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

Werken met grote resultatensets

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

// 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 gebruiken

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 gebruiken

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

Modus voor hoge gelijktijdigheid (HC)

High-concurrency (HC) modus helpt .NET-applicaties om gelijktijdige Spark SQL-workloads uit te voeren zonder voor elke ADONET-verbinding een aparte klassieke Spark-sessie te provisioneren. Fabric kan compatibele verbindingen in dezelfde serverbeheerde Livy-sessie plaatsen, terwijl elke verbinding een geïsoleerde Read-Eval-Print Loop (REPL) krijgt voor de uitvoering van een statement.

Dit model kan de opstarttijd van de verbinding verkorten, herhaalde Spark-sessieprovisioning vermijden en de capaciteit van Fabric Spark efficiënter benutten. Je applicatie blijft standaard ADO.NET API's gebruiken, waaronder , , , , OpenAsyncen Close. DbDataReaderDbCommandDbConnection

HC-modus moet worden ingeschakeld. Als je het niet inschakelt, gebruikt de driver het klassieke Livy-sessiepad.

Kies tussen HC en classic mode

Gebruik HC-modus wanneer:

• Een ASP.NET-service behandelt gelijktijdige verzoeken die verbindingen openen en Spark SQL uitvoeren.
• Een werkservice, geplande taak of parallelle gegevenspijplijn veroorzaakt pieken in ADO.NET-verbindingen.
• Meerdere verbindingen richten zich op dezelfde Fabric-werkruimte en lakehouse en gebruiken compatibele Spark-configuraties.
• Het verkorten van de opstarttijd van de verbinding en het herhaald provisioneren van Spark-sessies is belangrijk.
• Je workload kan gebruikmaken van gedeelde, serverbeheerde Spark-capaciteit, terwijl de uitvoering van statements geïsoleerd blijft door REPL.

Gebruik de klassieke modus wanneer:

• Je applicatie gebruikt slechts één of een paar langlopende verbindingen.
• Elke verbinding vereist een speciale Spark-sessie voor strikte werklast- of resource-isolatie.
• Verbindingen vereisen aanzienlijk verschillende Spark-configuraties die geen onderliggende sessie zouden moeten delen.
• Het Fabric Livy-eindpunt voor de doelwerkruimte en het lakehouse biedt geen ondersteuning voor HC-modus.

Hoe HC-verbindingen werken

Wanneer je applicatie Open of OpenAsync aanroept en er geen compatibele gepoolde verbinding beschikbaar is, doet de driver het volgende:

1. Vraagt een HC-sessie aan bij Fabric.
2. Wacht tot de sessie klaar is, tot de geconfigureerde acquisitie-timeout.
3. Verbindt de ADONET-verbinding met de toegewezen HC-sessie en REPL.
4. Leidt opdrachten, query's, annuleringsverzoeken en opschoonbewerkingen via de HC-eindpunten.

Aparte, gelijktijdig gehuurde HC-sessies gebruiken aparte REPL's. Opdrachten via één verbinding delen dezelfde HC-sessie en REPL.

Client-side pooling is standaard ingeschakeld. Het sluiten of verwijderen van een in aanmerking komende verbinding levert normaal gesproken de fysieke HC-sessie en REPL terug aan de process-lokale pool voor hergebruik; het geeft de toewijzing niet per se op afstand vrij. Wanneer pooling is uitgeschakeld, wordt HC opgeschoond wanneer de fysieke verbinding wordt gesloten. Blijf statements gebruiken using zodat logische verbindingen snel terugkeren.

Activeer HC-modus

HC-modus moet worden ingeschakeld. Als je het weglaat hcEnabled of op false zet, gebruikt de driver het klassieke Livy-sessiepad.

Stel eigenschap hcEnabled in op true om een HC-sessie te verkrijgen:

hcEnabled=true;

Sessiebundeling configureren

HcSessionTag biedt een aanwijzing aan de serverzijde om compatibele HC-sessies onder te brengen in een onderliggende Livy-sessie. Een matchende tag garandeert geen plaatsing in dezelfde onderliggende sessie.

Als je de tag weglaat of een lege of alleen witruimte waarde opgeeft, stuurt de driver deze niet in het acquire-verzoek. Het weglaten van de tag schakelt HC-modus of service-side packing niet uit. Stel een expliciete tag in wanneer gerelateerde applicatie-instanties of workloads moeten worden overwogen voor gedeelde capaciteit. Gebruik een stabiel, niet-gevoelig operationeel label, zoals reporting-service of nightly-etl. Voeg geen geheimen, toegangstokens, persoonlijke gegevens, klantidentificaties of querytekst toe.

De Spark-configuratie beïnvloedt ook de compatibiliteit van sessies. Gebruik HcConfOverrides om toegestane Spark-instellingen te bieden voor het aanmaken van HC-sessies:

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

Voor meerdere overschrijvingen zet u de volledige HcConfOverrides-waarde tussen aanhalingstekens. Een niet-geciteerde puntkomma begint een andere eigenschap van de buitenste connection string; deze breidt HcConfOverrides niet uit. De parser accepteert waarden tussen enkele of dubbele aanhalingstekens, behoudt puntkomma's en gelijkheidstekens binnen waarden tussen aanhalingstekens, en decodeert verdubbelde overeenkomende aanhalingstekens ('' of ""). Witruimte rond eigendomsnamen en aan de buitenranden van niet-geciteerde waarden wordt genegeerd. Witruimte binnen niet-aangehaalde waarden en alle witruimte binnen aangehaalde waarden blijft behouden. Lege waarden overschrijven de standaardinstellingen van de omgeving, en de laatst gedupliceerde eigenschap wint.

Je kunt ook LivyConnectionStringBuilder de offerte laten verzorgen:

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;

Deze voorbeelden vereisen Microsoft ADO.NET Driver versie 2.0.1 of hoger. Voeg je workspace- en lakehouse-identificaties toe voordat je een verbinding opent. Beide overschrijvingen worden in de HC-create-session-aanvraag als afzonderlijke conf-items verzonden. Elke overschrijving moet een van deze hoofdlettergevoelige sleutels gebruiken:

• 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

Verkeerd gevormde aanhalingstekens worden afgewezen zonder de inhoud van de verbindingsstring in de parsefout op te nemen.

Gebruik consistente tags en configuratiewaarden over verbindingen die bedoeld zijn om capaciteit te delen. Fabric bepaalt of een verzoek een bestaande sessie kan gebruiken of een andere sessie vereist.

Stel de acquisitietiming in

Gebruik de volgende instellingen om te bepalen hoe lang de driver wacht op een HC-sessie:

Voor de meeste workloads moet je de standaardwaarden behouden. Verhoog de acquisitie-timeout alleen wanneer het opstarten van de capaciteit regelmatig langer dan vijf minuten duurt.

Gebruik HC-modus met verbindingspooling

HC-modus en ADONET verbindingspooling adresseren verschillende lagen:

• HC-modus beheert gedeelde Fabric Spark-capaciteit en Livy-sessies op de server.
• ADO.NET-verbindingspooling hergebruikt verbindingsresources die door het stuurprogramma in de clienttoepassing worden beheerd.

Je kunt beide functies inschakelen. Connection pooling vermindert herhaalde client-side verbindingsopstelling, terwijl HC-modus herhaalde server-side Spark-sessieprovisionering vermindert. Pas de verbindingspool op de verwachte gelijktijdigheid van de applicatie in plaats van een grote pool te gebruiken om onnodig parallel werk te creëren.

In HC-modus AutoReconnect=true wordt een mislukte opdracht niet transparant opnieuw afgespeeld na een stale-sessiefout. De applicatie ontvangt de uitzondering en moet beslissen of het opnieuw proberen van de operatie veilig is.

Schakel HC-modus uit

Om de klassieke modus voor nieuwe verbindingen te gebruiken, verwijder HcEnabled je deze uit de verbindingsreeks of stel je deze in opfalse:

HcEnabled=false

De wijziging beïnvloedt nieuwe verbindingen en spoelt bestaande gepoolde HC-sessies niet door. Sluit logische verbindingen zoals gebruikelijk of geef ze vrij; fysieke sessies die daarvoor in aanmerking komen, kunnen in de clientpool blijven totdat ze buiten gebruik worden gesteld.

ADO.NET beperkingen

• Transacties worden niet ondersteund.
• Commando's ondersteunen alleen tekstcommandomodus. De opdrachtmodi 'Stored-procedure' en 'table-direct' worden niet ondersteund.
• Prepare Doet niets.
• Een commando moet één instructie bevatten; de commandotekst met meerdere instructies wordt afgewezen.
• Gebruik aparte, gelijktijdig open verbindingen voor gelijktijdige workloads. Commando’s via één verbinding delen dezelfde sessie en REPL.

Koppeling van gegevenstypen

Het stuurprogramma wijst Spark SQL-gegevenstypen toe aan .NET-typen:

Werken met complexe typen

Het HC-resultaatpad serialiseert niet betrouwbaar native geneste ARRAY-, MAP- of STRUCT-waarden als JSON. Zet complexe waarden in Spark SQL om naar JSON-tekenreeksen voordat u deze deserialiseert:

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

Troubleshooting

Deze sectie biedt richtlijnen voor het oplossen van veelvoorkomende problemen die je kunt tegenkomen bij het gebruik van de Microsoft ADO.NET Driver for Fabric Data Engineering.

Veelvoorkomende problemen

In de volgende secties worden veelvoorkomende problemen en hun oplossingen beschreven:

Verbindingsfouten

Probleem: Kan niet aansluiten op Fabric

Oplossingen:

1. Controleer FabricWorkspaceID en FabricLakehouseID zijn juiste GUID's
2. Azure CLI-verificatie controleren: az account show
3. Zorg ervoor dat u over de juiste Fabric werkruimtemachtigingen beschikt
4. Controleer de netwerkverbinding met api.fabric.microsoft.com

Authenticatiefouten

Probleem: verificatie mislukt met Azure CLI

Oplossingen:

• Voer az login uit om referentiegegevens te vernieuwen
• Controleer de juiste tenant: az account set --subscription <subscription-id>
• Controleer de geldigheid van het token: az account get-access-token --resource https://api.fabric.microsoft.com

Querytime-outs

Probleem: Time-outs van query's in grote datasets

Oplossingen:

• Verhoog de time-out van de afschrift: LivyStatementTimeoutSeconds=1200.
• Gebruik LIMIT clausule om de resultaatgrootte tijdens de ontwikkeling te beperken
• Zorg ervoor dat het Spark-cluster voldoende resources heeft

Verbinding of HC-acquisitietime-out

Probleem: Een verbinding loopt uit tijdens het wachten op een pooled connection of een HC-sessie

Oplossingen:

• Raadpleeg HttpConnectionTimeoutInSeconds voor de wachttijd voor de clientpool en het tot stand brengen van een HTTP-verbinding.
• Voor HC-acquisitie, verhoog hcAcquireTimeoutSeconds binnen het ondersteunde bereik van 120 tot en met 3.600 seconden.
• Beschikbaarheid van Fabric capaciteit controleren
• Controleren of de werkruimte geen sessielimieten heeft bereikt

Logboekregistratie inschakelen

Bij het oplossen van problemen kan gedetailleerde logging je helpen de oorzaak te achterhalen. Configureer logregistratie via de verbindingsreeks:

Gedetailleerde logboekregistratie inschakelen via verbindingsreeks:

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

Als je LogFilePath of een globale logconfiguratie niet instelt, schrijft de driver op Windows logbestanden weg onder %LOCALAPPDATA%\FabricSparkAdoNet\Logs.

Logboekniveaus:

• Trace: De meeste uitgebreide, omvat alle API-aanroepen
• Debug: Gedetailleerde informatie over foutopsporing
• Information: Algemene informatie (standaard)
• Warning: alleen waarschuwingen
• Error: alleen fouten

Verwante inhoud

• Apache Spark Runtimes in Fabric
• Fabric Runtime 1.3
• Wat is de Livy-API voor Data Engineering?
• Microsoft JDBC Driver voor Fabric Data Engineering
• Microsoft ODBC Driver voor Fabric Data Engineering