Microsoft ADO.NET-driver til Microsoft Fabric Data Engineering

ADO.NET er en bredt anvendt dataadgangsteknologi i .NET-økosystemet, som gør det muligt for applikationer at forbinde til og arbejde med data fra databaser og big data-platforme.

Microsoft ADO.NET Driver for Fabric Data Engineering lader dig forbinde, forespørge og administrere Spark-arbejdsbelastninger i Fabric med pålideligheden og enkelheden fra standard ADO.NET-mønstre. Drevet på Fabric's Livy API'er leverer sikker og fleksibel Spark SQL-forbindelse til dine .NET-applikationer ved hjælp af familiar DbConnection, DbCommand, og DbDataReader abstraktioner.

Vigtige funktioner

• ADO.NET API'er: Velkendte DbConnection, DbCommand, , DbDataReaderDbParameter, og DbProviderFactory abstraktioner til Spark SQL-forbindelse
• Microsoft Entra ID-autentificering: Flere autentificeringsflows, herunder Azure CLI, interaktiv browser, klientoplysninger, certifikatbaseret og adgangstoktoeifikation
• Spark SQL Native Query Support: Direkte udførelse af Spark SQL-udsagn med parameteriserede forespørgsler
• Omfattende understøttelse af datatyper: Understøttelse af alle Spark SQL-datatyper inklusive komplekse typer (ARRAY, MAP, STRUCT)
• Connection Pooling: Indbygget administration af forbindelsespoolen for forbedret ydeevne
• Genbrug af sessioner: Effektiv Spark-sessionstyring for at reducere opstartsforsinkelse
• Højsamtidige sessioner: Vælg til delt Fabric Livy-kapacitet med separate REPL'er for samtidig lejede HC-sessioner
• Async Prefetch: Baggrundsindlæsning af data for forbedret ydeevne med store resultatsæt
• Auto-genforbindelse: Klassisk sessionsgendannelse efter forbindelsesfejl; HC-fejl fremkommer ved applikationsstyret genprøvning

Forudsætninger

Før du bruger Microsoft ADO.NET Driver for Fabric Data Engineering, skal du sikre dig, at du har:

• .NET Runtime: .NET 8.0 eller senere
• Fabric Access: Adgang til et Fabric-arbejdsområde med Data Engineering-funktioner
• Azure Entra ID Credentials: Passende legitimationsoplysninger til autentificering
• Workspace og Lakehouse ID'er: GUID-identifikatorer for dit Fabric workspace og lakehouse
• Azure CLI (valgfrit): Required for Azure CLI authentication method

Download, inkludér, referer og verificér

Download NuGet-pakken

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

Reference NuGet-pakke i dit projekt

Inkluder den downloadede NuGet-pakke i dit projekt og tilføj en reference til pakken til din projektfil:

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

Kontrollér installationen

Efter inkludering og reference, skal du sikre dig, at pakken er tilgængelig i dit projekt:

using Microsoft.Spark.Livy.AdoNet;

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

Eksempel på hurtigstart

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

Forbindelsesstrengsformat

Grundformat

Microsoft ADO.NET Driver bruger standard ADO.NET forbindelsesstrengsformat:

Parameter1=Value1;Parameter2=Value2;...

Påkrævede parametre

Valgfrie parametre

Forbindelsesindstillinger

Indstillinger for forbindelsespoolen

Høje samtidighedsindstillinger

Logningsindstillinger

Cross-driver-aliaser: Driveren accepterer JDBC- og ODBC-ejendomsnavne ud over native ADO.NET-navne (f.eks. WorkspaceId kort til FabricWorkspaceID, LakehouseId kort til FabricLakehouseID). Alle ejendomsnavne er små og små bogstaver.

Eksempel på forbindelsesstrenge

Basic connection (Azure CLI authentication)

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

Høj samkørselsforbindelse

Høj samtidighed er tilgængelig for Microsoft Fabric-forbindelser. Sæt HcEnabled=true; de standard ADO.NET-forbindelses- og kommando-API'er forbliver uændrede. Brug den uversionerede Fabric API-vært for Server; driveren bruger FabricVersion=v1 og LivyApiVersion=2023-12-01 som standard, når den bygger HC-endpointet.

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

For fuld konfigurationsvejledning, se afsnittet omHigh-Concurrency (HC) Mode .

Med forbindelsespooling-muligheder

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

Med automatisk genforbindelse og logning

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

Godkendelse

Microsoft ADO.NET Driver understøtter flere autentificeringsmetoder via Microsoft Entra ID (tidligere Azure Active Directory). Autentificering konfigureres ved hjælp af parameteren AuthFlow i forbindelsesstrengen.

Godkendelsesmetoder

Azure CLI authentication

Bedst til: Udvikling og testning

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

Forudsætninger:

• Azure CLI installeret: az --version
• Indlogget: az login

Interaktiv browserautentificering

Bedst til: Brugerrettede applikationer

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

Adfærd:

• Åbner et browservindue til brugerautentificering
• Oplysninger caches til efterfølgende forbindelser

Klientlegitimation (Service Principal) Autentificering

Bedst til: Automatiserede tjenester og baggrundsjobs

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

Påkrævede parametre:

• AuthTenantID: Azure lejer-ID
• AuthClientID: Application (klient) ID fra Microsoft Entra ID
• AuthClientSecret: Klienthemmelighed fra Microsoft Entra ID

Certifikatbaseret godkendelse

Bedst til: Virksomhedsapplikationer, der kræver certifikatbaseret autentificering

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

Påkrævede parametre:

• AuthTenantID: Azure lejer-ID
• AuthClientID: Applikations-ID (klient)
• AuthCertificatePath: Sti til PFX/PKCS12 certifikatfil
• AuthCertificatePassword: Certifikatadgangskode

Adgangstoksgodkendelse

Bedst til: Brugerdefinerede autentificeringsscenarier

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

Eksempler på anvendelse

Grundlæggende forbindelse og forespørgsel

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

Parameteriserede forespørgsler

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 for enkeltværdier

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

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

ExecuteNonQuery for DML-operationer

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

Arbejde med store resultatmængder

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

Skemaopdagelse

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

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

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

Høj-samtidighed (HC) tilstand

High-concurrency (HC) tilstand hjælper .NET-applikationer med at køre samtidige Spark SQL-arbejdsbelastninger uden at provisionere en separat klassisk Spark-session for hver ADO.NET-forbindelse. Fabric kan placere kompatible forbindelser i den samme serveradministrerede Livy-session, samtidig med at hver forbindelse får en isoleret Read-Eval-Print Loop (REPL) til sætningsudførelse.

Denne model kan reducere forbindelsesopstartstiden, undgå gentagen Spark-sessionsprovisionering og udnytte Fabric Spark-kapaciteten mere effektivt. Din applikation fortsætter med at bruge standard ADO.NET API'er, herunder DbConnection, DbCommand, , DbDataReader, OpenAsyncog Close.

HC-tilstand er opt-in. Hvis du ikke aktiverer det, bruger driveren den klassiske Livy-sessionssti.

Vælg mellem HC og klassisk tilstand

Brug HC-tilstand når:

• En ASP.NET-tjeneste håndterer samtidige forespørgsler, der åbner forbindelser og kører Spark SQL.
• En worker-service, planlagt job eller parallel datapipeline skaber bursts af ADO.NET-forbindelser.
• Flere forbindelser sigter mod det samme Fabric-arbejdsområde og lakehouse og bruger kompatible Spark-konfigurationer.
• At reducere opstartstiden for forbindelsen og gentagne Spark-sessioner er vigtigt.
• Din arbejdsbyrde kan bruge delt, serverstyret Spark-kapacitet, samtidig med at statement-udførelsen isoleres af REPL.

Brug klassisk tilstand, når:

• Din applikation bruger kun én eller få langvarige forbindelser.
• Hver forbindelse kræver en dedikeret Spark-session til streng arbejdsbelastning eller ressourceisolering.
• Forbindelser kræver væsentligt forskellige Spark-konfigurationer, som ikke burde dele en underliggende session.
• Fabric Livy-endpointet for det målrettede arbejdsområde og lakehouse understøtter ikke HC-tilstand.

Hvordan HC-forbindelser fungerer

Når din applikation kalder Open eller OpenAsync og der ikke er nogen kompatibel poolforbindelse, er driveren:

1. Anmoder om en HC-session fra Fabric.
2. Venter på, at sessionen bliver klar, indtil den konfigurerede anskaffelsestimeout.
3. Forbinder ADO.NET-forbindelsen til den tildelte HC-session og REPL.
4. Ruter kommandoer, forespørgsler, annulleringsanmodninger og oprydningsoperationer gennem HC-endepunkterne.

Separate, samtidig lejede HC-sessioner bruger separate REPL'er. Kommandoer på én forbindelse deler forbindelsens HC-session og REPL.

Client-side pooling er aktiveret som standard. Lukning eller bortskaffelse af en berettiget forbindelse returnerer normalt dens fysiske HC-session og REPL til proces-lokal puljen til genbrug; det frigiver ikke nødvendigvis tildelingen eksternt. Med pooling deaktiveret udfører lukning af den fysiske forbindelse HC-oprydning. Fortsæt med at bruge using sætninger, så logiske forbindelser vender tilbage hurtigt.

Aktivér HC-tilstand

HC-tilstand er opt-in. Hvis du udelader hcEnabled eller sætter den til falsk, bruger driveren den klassiske Livy-sessionsrute.

Sæt ejendommen hcEnabled til sand for at få en HC-session:

hcEnabled=true;

Konfigurér session packing

HcSessionTag giver et serverside-tip til at pakke kompatible HC-sessioner ind i en underliggende Livy-session. Et matchende tag garanterer ikke, at du bliver placeret i samme underliggende session.

Hvis du udelader tagget eller angiver en tom værdi eller kun hvid plads, sender driveren det ikke i acquise-anmodningen. At udelade tagget deaktiverer ikke HC-tilstand eller service-side packing. Sæt et eksplicit tag, når relaterede applikationsinstanser eller arbejdsbelastninger skal overvejes for delt kapacitet. Brug en stabil, ikke-følsom operationel label, såsom reporting-service eller nightly-etl. Inkluder ikke hemmeligheder, adgangstoks, personlige data, kundeidentifikatorer eller forespørgselstekst.

Spark-konfigurationen påvirker også sessionskompatibiliteten. Brug HcConfOverrides til at give tilladelseslistede Spark-indstillinger til oprettelse af HC-sessioner:

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

For flere overstyringer, giv et tilbud på hele HcConfOverrides værdien. Et ikke-citeret semikolon starter en anden ydre forbindelsesstrengsegenskab; det udvider HcConfOverridesikke . Parseren accepterer enkelt- eller dobbeltanførte værdier, bevarer semikolon og ligetegn inden for anførselsværdier og afkoder dobbelt matchende citationstegn (''""eller ). Hvidrum omkring ejendomsnavne og ved yderkanterne af ikke-citerede værdier ignoreres. Mellemrum inden for anførselsværdier uden anførselstegn og alt mellemrum inden for anførselsværdier bevares. Tomme værdier tilsidesætter miljøstandarder, og den sidste duplikerede egenskab vinder.

Du kan også lade LivyConnectionStringBuilder dig håndtere tilbuddet:

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;

Disse eksempler kræver Microsoft ADO.NET Driver version 2.0.1 eller nyere. Tilføj dine workspace- og lakehouse-identifikatorer, før du åbner en forbindelse. Begge overstyringer sendes i HC-oprettelsessessionsanmodningen som separate conf poster. Hver overstyring skal bruge en af disse kasusfølsomme taster:

• 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

Fejlformede citater afvises uden at inkludere forbindelsesstrengens indhold i parsefejlen.

Brug ensartede tags og konfigurationsværdier på tværs af forbindelser, der er beregnet til at dele kapacitet. Fabric afgør, om en anmodning kan bruge en eksisterende session eller kræver en anden session.

Konfigurer anskaffelsestiming

Brug følgende indstillinger til at styre, hvor længe driveren venter på en HC-session:

For de fleste arbejdsbelastninger skal du beholde standardværdierne. Øg kun opkøbstiden, når kapacitetsopstart regelmæssigt tager længere end fem minutter.

Brug HC-tilstand med forbindelsespooling

HC-tilstand og ADONET-forbindelsespooling adresserer forskellige lag:

• HC-tilstand håndterer delt Fabric Spark-kapacitet og Livy-sessioner på serveren.
• ADO.NET forbindelsespooling genbruger driver-administrerede forbindelsesressourcer i klientapplikationen.

Du kan aktivere begge funktioner. Connection pooling reducerer gentagen klient-side forbindelsesopsætning, mens HC-tilstand reducerer gentagen server-side Spark-sessionsprovisionering. Dimensioner forbindelsespuljen efter applikationens forventede samtidighed i stedet for at bruge en stor pulje til at skabe unødvendigt parallelt arbejde.

I HC-tilstand AutoReconnect=true afspiller den ikke gennemsigtigt en fejl efter en fejl i en stale-session. Applikationen modtager undtagelsen og skal beslutte, om det er sikkert at prøve operationen igen.

Deaktiver HC-tilstand

For at bruge klassisk tilstand til nye forbindelser, fjern HcEnabled fra forbindelsesstreng eller sæt den til false:

HcEnabled=false

Ændringen påvirker nye forbindelser og fjerner ikke eksisterende sammenlagte HC-sessioner. Luk eller bortskaff logiske forbindelser normalt; berettigede fysiske sessioner kan forblive i klientpuljen, indtil de er pensioneret.

ADO.NET-begrænsninger

• Transaktioner understøttes ikke.
• Kommandoer understøtter kun tekstkommando-tilstand. Stored-procedure og table-direct kommandotilstande understøttes ikke.
• Prepare gør ingenting.
• En kommando skal indeholde én sætning; kommandotekst med flere sætninger afvises.
• Brug separate, samtidig åbne forbindelser til samtidige arbejdsbelastninger. Kommandoer på én forbindelse deler dens session og REPL.

Datatypetilknytning

Driveren mapper Spark SQL-datatyper til .NET-typer:

Arbejde med komplekse typer

HC-resultatstien serialiserer ikke pålideligt native indlejrede ARRAY-, MAP- eller STRUCT-værdier som JSON. Project komplekse værdier til JSON-strenge i Spark SQL, før du deserialiserer dem:

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

Fejlfinding

Dette afsnit giver vejledning til at løse almindelige problemer, du kan støde på ved brug af Microsoft ADO.NET Driver for Fabric Data Engineering.

Almindelige problemer

Følgende afsnit beskriver almindelige problemer og deres løsninger:

Forbindelsesfejl

Problem: Kan ikke forbinde til Fabric

Løsninger:

1. Verificér FabricWorkspaceID og FabricLakehouseID er korrekte GUID'er
2. Tjek Azure CLI autentificering: az account show
3. Sørg for, at du har passende Fabric-arbejdsområdetilladelser
4. Verificér netværksforbindelsen til api.fabric.microsoft.com

Godkendelsesfejl

Problem: Autentificering fejler med Azure CLI

Løsninger:

• Kør az login for at opdatere legitimationsoplysninger
• Verificér korrekt lejer: az account set --subscription <subscription-id>
• Tjek tokens gyldighed: az account get-access-token --resource https://api.fabric.microsoft.com

Timeout for forespørgsler

Problem: Forespørgsler går ud på tid på store tabeller

Løsninger:

• Øg timeout for kontoudtoget: LivyStatementTimeoutSeconds=1200.
• Brug LIMIT klausulen til at begrænse resultatstørrelsen under udviklingen
• Sørg for, at Spark-klyngen har tilstrækkelige ressourcer

Forbindelses- eller HC-anskaffelsestimeout

Problem: En forbindelse går ud på tid, mens man venter på en poolet forbindelse eller en HC-session

Løsninger:

• For klientpool-ventetid og HTTP-forbindelsesetablering, gennemgå HttpConnectionTimeoutInSeconds.
• For HC-opsamling, øg hcAcquireTimeoutSeconds inden for det understøttede interval fra 120 til 3.600 sekunder.
• Tjek tilgængelighed af Fabric-kapacitet
• Bekræfte, at arbejdsområdet ikke har nået sessionsgrænser

Aktiver logning

Når du fejlsøger problemer, kan detaljeret logning hjælpe dig med at identificere den egentlige årsag. Konfigurér logging gennem forbindelsesstreng:

For at muliggøre detaljeret logning via forbindelsesstreng:

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

Hvis du ikke sætter LogFilePath en global logningskonfiguration, skriver driveren logs under %LOCALAPPDATA%\FabricSparkAdoNet\Logs på Windows.

Log-niveauer:

• Trace: Mest omstændelig, inkluderer alle API-kald
• Debug: Detaljeret fejlfinding information
• Information: Generel information (standard)
• Warning: Kun advarsler
• Error: Kun fejl

Relateret indhold

• Apache Spark Runtimes i Fabric
• Stof Driftstid 1.3
• Hvad er Livy API til Data Engineering
• Microsoft JDBC Driver til Fabric Data Engineering
• Microsoft ODBC Driver til Fabric Data Engineering