Microsoft ADO.NET-drivrutin för Microsoft Fabric Data Engineering

ADO.NET är en allmänt antagen dataåtkomstteknik i .NET-ekosystemet som gör det möjligt för program att ansluta till och arbeta med data från databaser och stordataplattformar.

Microsoft ADO.NET Driver för Fabric Data Engineering låter dig koppla samman, fråga och hantera Spark-arbetsbelastningar i Fabric med samma tillförlitlighet och enkelhet som standard ADO.NET-mönster. Byggd på Fabric:s Livy-API:er erbjuder drivrutinen säker och flexibel Spark SQL-anslutning till dina .NET-applikationer med hjälp av bekanta DbConnection, DbCommand, och DbDataReader abstraktioner.

Viktiga funktioner

• ADO.NET-API:er: Bekanta DbConnection, DbCommand, DbDataReader, DbParameter, och DbProviderFactory abstraktioner för Spark SQL-anslutning
• Microsoft Entra-ID-autentisering: Flera autentiseringsflöden, inklusive Azure CLI, interaktiv webbläsare, klientautentiseringsuppgifter, certifikatbaserad och åtkomsttokenautentisering
• Stöd för Spark SQL Native Query: Direktkörning av Spark SQL-instruktioner med parametriserade frågor
• Omfattande stöd för datatyper: Stöd för alla Spark SQL-datatyper, inklusive komplexa typer (ARRAY, MAP, STRUCT)
• Anslutningspooler: Inbyggd hantering av anslutningspooler för bättre prestanda
• Återanvändning av session: Effektiv Spark-sessionshantering för att minska startfördröjningen
• Sessioner med hög samtidighet: Välj att dela Fabric Livy-kapacitet med separata REPL:ar för samtidigt hyrda HC-sessioner
• Async Prefetch: Inläsning av bakgrundsdata för bättre prestanda med stora resultatuppsättningar
• Auto-återanslutning: Klassisk sessionsåterställning efter anslutningsfel; HC-fel upptäcks vid applikationsstyrda återförsök

Förutsättningar

Innan du använder Microsoft ADO.NET Driver för Fabric Data Engineering, se till att du har:

• .NET Runtime: .NET 8.0 eller senare
• Fabric Access: Tillgång till en Fabric-arbetsyta med Data Engineering-funktioner
• Autentiseringsuppgifter för Azure Entra-ID: Lämpliga autentiseringsuppgifter för autentisering
• Workspace- och Lakehouse-ID: GUID-identifierare för din Fabric-arbetsyta och lakehouse
• Azure CLI (valfritt): Krävs för Azure CLI-autentiseringsmetod

Ladda ned, inkludera, referera till och verifiera

Ladda ned NuGet-paket

• Ladda ner Microsoft ADO.NET Driver för Fabric Data Engineering (zip)
• Ladda ner Microsoft ADO.NET Driver för Fabric Data Engineering (tar)

Referera till NuGet-paketet i projektet

Inkludera det nedladdade NuGet-paketet i projektet och lägg till en referens för paketet i projektfilen:

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

Verifiera installationen

Efter inkludering och referens kontrollerar du att paketet är tillgängligt i projektet:

using Microsoft.Spark.Livy.AdoNet;

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

Snabbstartsexempel

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 för anslutningssträng

Grundläggande format

Microsoft ADO.NET-drivrutinen använder standardformatet för ADO.NET-anslutningssträngar:

Parameter1=Value1;Parameter2=Value2;...

Obligatoriska parametrar

Valfria parametrar

Anslutningsinställningar

Inställningar för anslutningspool

Inställningar för hög parallellism

Loggningsinställningar

Alias för flera drivrutiner: Drivrutinen accepterar JDBC- och ODBC-egenskapsnamn utöver interna ADO.NET namn (t.ex. WorkspaceId mappar till FabricWorkspaceID, LakehouseId mappar till FabricLakehouseID). Alla egenskapsnamn är skiftlägesokänsliga.

Exempel på anslutningssträngar

Grundläggande anslutning (Azure CLI-autentisering)

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

Anslutning med hög samtidighet

Hög samtidighet är tillgänglig för Microsoft Fabric-anslutningar. Sätt HcEnabled=true; de standardiserade ADO.NET-anslutnings- och kommando-API:erna förblir oförändrade. Använd den versionslösa Fabric API-värdadressen för Server; drivrutinen använder FabricVersion=v1 och LivyApiVersion=2023-12-01 som standard när den bygger HC-slutpunkten.

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

Fullständig vägledning för konfiguration finns i avsnittet High-Concurrency (HC) Mode.

Med alternativ för anslutningspooler

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

Med automatisk återanslutning och loggning

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

Authentication

Microsoft ADO.NET Driver stöder flera autentiseringsmetoder via Microsoft Entra-ID (tidigare Azure Active Directory). Autentisering konfigureras med hjälp av parametern AuthFlow i anslutningssträngen.

Autentiseringsmetoder

Azure CLI-autentisering

Bäst för: Utveckling och 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();

Prerequisites:

• Azure CLI installerat: az --version
• Inloggad: az login

Interaktiv webbläsarautentisering

Bäst för: Användarinriktade program

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

Beteende:

• Öppnar ett webbläsarfönster för användarautentisering
• Autentiseringsuppgifter cachelagras för efterföljande anslutningar

Klientautentisering (Tjänstehuvudperson)

Bäst för: Automatiserade tjänster och bakgrundsjobb

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

Obligatoriska parametrar:

• AuthTenantID: Azure-klientorganisations-ID
• AuthClientID: Program-ID (klient) från Microsoft Entra-ID
• AuthClientSecret: Klienthemlighet från Microsoft Entra-ID

Certifikatbaserad autentisering

Bäst för: Företagsprogram som kräver certifikatbaserad autentisering

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

Obligatoriska parametrar:

• AuthTenantID: Azure-klientorganisations-ID
• AuthClientID: Program-ID (klient)-ID
• AuthCertificatePath: Sökväg till PFX/PKCS12-certifikatfilen
• AuthCertificatePassword: Certifikatlösenord

Åtkomsttokenautentisering

Bäst för: Scenarier för anpassad autentisering

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

Exempel på användning

Grundläggande anslutning och fråga

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

Parametriserade frågor

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 enkla värden

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-åtgärder

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

Arbeta med stora resultatuppsättningar

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

Upptäckt av schema

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

Använda 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();

Använda 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...

Läge för hög samtidighet (HC)

Högkonkurrensläge (HC) hjälper .NET-applikationer att köra samtidiga Spark SQL-arbetsbelastningar utan att upprätta en separat klassisk Spark-session för varje ADO.NET-anslutning. Fabric kan placera kompatibla anslutningar i samma serverhanterade Livy-session samtidigt som varje anslutning får en isolerad Read-Eval-Print Loop (REPL) för satsexekvering.

Denna modell kan minska anslutningsstarttiden, undvika upprepad Spark-sessionsprovisionering och använda Fabric Spark-kapacitet mer effektivt. Din applikation fortsätter att använda standard-ADO.NET-API:er, inklusive DbConnection, DbCommand, DbDataReader, , OpenAsyncoch Close.

HC-läget är frivilligt. Om du inte aktiverar det använder drivrutinen den klassiska Livy-sessionsvägen.

Välj mellan HC och klassiskt läge

Använd HC-läge när:

• En ASP.NET-tjänst hanterar samtidiga förfrågningar som öppnar anslutningar och kör Spark SQL.
• En arbetstjänst, schemalagt jobb eller parallell datapipeline skapar burstar av ADO.NET-anslutningar.
• Flera anslutningar riktar sig mot samma Fabric-arbetsområde och lakehouse och använder kompatibla Spark-konfigurationer.
• Att minska anslutningsstarttiden och upprepad Spark-sessionsprovisionering är viktigt.
• Din arbetsbelastning kan använda delad, serverhanterad Spark-kapacitet samtidigt som satsexekveringen hålls isolerad av REPL.

Använd klassiskt läge när:

• Din applikation använder bara en eller några långlivade anslutningar.
• Varje anslutning kräver en dedikerad Spark-session för strikt arbetsbelastning eller resursisolering.
• Anslutningar kräver väsentligt olika Spark-konfigurationer som inte borde dela en underliggande session.
• Fabric Livy-endpointen för målarbetsytan och lakehouse stöder inte HC-läge.

Hur HC-anslutningar fungerar

När din applikation anropar Open eller OpenAsync och ingen kompatibel poolanslutning finns tillgänglig, följer drivrutinen:

1. Begär en HC-session från Fabric.
2. Väntar tills sessionen är klar, fram till den konfigurerade anskaffningstimeouten.
3. Kopplar ADO.NET-anslutningen till den tilldelade HC-sessionen och REPL.
4. Dirigerar kommandon, frågor, begäranden om avbrott och rensningsåtgärder via HC-slutpunkterna.

Separata, samtidigt hyrda HC-sessioner använder separata REPL:er. Kommandon på en anslutning delar den anslutningens HC-session och REPL.

Klientpooling är aktiverad som standard. Att stänga eller kassera en kvalificerad anslutning återför normalt dess fysiska HC-session och REPL till den processlokala poolen för återanvändning; det frigör inte nödvändigtvis tilldelningen på fjärrsidan. När poolning är inaktiverad innebär stängning av den fysiska anslutningen att rensning av HC utförs. Fortsätt använda using satser så att logiska kopplingar återkommer snabbt.

Aktivera HC-läge

HC-läget är frivilligt. Om du utelämnar hcEnabled eller sätter det till falskt, använder drivrutinen den klassiska Livy-sessionsvägen.

Ange egenskapen hcEnabled till true för att upprätta en HC-session:

hcEnabled=true;

Konfigurera packning av sessioner

HcSessionTag ger en anvisning på serversidan för att samla kompatibla HC-sessioner i en underliggande session i Livy. En matchande tagg garanterar inte placering i samma underliggande session.

Om du utelämnar taggen eller anger ett tomt eller endast whitespace-värde, skickar drivrutinen det inte i acquire-förfrågan. Att utelämna taggen inaktiverar inte HC-läge eller service-side packing. Sätt en explicit tagg när relaterade applikationsinstanser eller arbetsbelastningar ska beaktas för delad kapacitet. Använd en stabil, icke-känslig operativ etikett, såsom reporting-service eller nightly-etl. Inkludera inte hemligheter, åtkomsttokens, personuppgifter, kundidentifierare eller förfrågningstext.

Spark-konfigurationen påverkar också sessionskompatibiliteten. Använd HcConfOverrides för att tillhandahålla tillåtna Spark-inställningar för skapande av HC-sessioner:

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

Vid flera åsidosättningar, sätt hela HcConfOverrides-värdet inom citationstecken. Ett semikolon utan citattecken startar en annan egenskap i den yttre anslutningssträngen; det utökar inte HcConfOverrides. Parsern accepterar enkla eller dubbelciterade värden, bevarar semikolon och likvärdiga tecken inom citerade värden, och avkodar dubbla matchande citattecken ('' eller ""). Blankutrymme runt egendomsnamn och vid ytterkanterna av icke-citerade värden ignoreras. Blanktecken i ociterade värden och alla blanktecken i citerade värden bibehålls. Tomma värden åsidosätter standardvärden för miljön, och den sista dubblerade egenskapen gäller.

Du kan också låta LivyConnectionStringBuilder dig hantera offert:

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;

Dessa exempel kräver Microsoft ADO.NET Driver version 2.0.1 eller senare. Lägg till dina workspace- och lakehouse-identifierare innan du öppnar en anslutning. Båda åsidosättningarna skickas i begäran om att skapa en session i HC som separata conf-poster. Varje överskrivning måste använda en av dessa kasuskänsliga nycklar:

• 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

Felaktigt formulerade citat avvisas utan att inkludera anslutningssträngsinnehåll i parsefelet.

Använd konsekventa taggar och konfigurationsvärden över anslutningar som är avsedda att dela kapacitet. Fabric avgör om en förfrågan kan använda en befintlig session eller om den kräver en annan session.

Konfigurera inhämtningstidpunkt

Använd följande inställningar för att styra hur länge föraren väntar på en HC-session:

För de flesta arbetsbelastningar, behåll standardvärdena. Öka anskaffningstiden endast när kapacitetsstart regelbundet tar längre än fem minuter.

Använd HC-läge med anslutningspoolning

HC-läge och ADONET-anslutningspoolning adresserar olika lager:

• HC-läget hanterar delad Fabric Spark-kapacitet och Livy-sessioner på servern.
• ADO.NET-anslutningspoolning återanvänder drivrutinshanterade anslutningsresurser i klientapplikationen.

Du kan aktivera båda funktionerna. Anslutningspoolning minskar den upprepade etableringen av anslutningar på klientsidan, medan HC-läge minskar den upprepade etableringen av Spark-sessioner på serversidan. Anpassa anslutningspoolens storlek efter programmets förväntade samtidighet i stället för att använda en stor pool som skapar onödigt parallellt arbete.

I HC-läget AutoReconnect=true spelas inte ett misslyckat kommando upp igen transparent efter ett stale-session-fel. Applikationen får undantaget och måste avgöra om det är säkert att försöka om operationen.

Inaktivera HC-läget

För att använda klassiskt läge för nya anslutningar, ta bort HcEnabled från reťazec pripojenia eller ställ in den till false:

HcEnabled=false

Förändringen påverkar nya anslutningar och rensar inte befintliga poolade HC-sessioner. Stäng eller avsluta logiska anslutningar på vanligt sätt. Kvalificerade fysiska sessioner kan ligga kvar i klientpoolen tills de tas ur bruk.

ADO.NET begränsningar

• Transaktioner stöds inte.
• Kommandon stöder endast textkommandoläge. Kommandolägena lagrad procedur och direkt tabellåtkomst stöds inte.
• Prepare gör ingenting.
• Ett kommando måste innehålla en sats; kommandotext med flera satser avvisas.
• Använd separata, samtidigt öppna anslutningar för samtidiga arbetsbelastningar. Kommandon på en anslutning delar dess session och REPL.

Datatypkartläggning

Drivrutinen mappar Spark SQL-datatyper till .NET-typer:

Arbeta med komplexa typer

HC-resultatsökvägen serialiserar inte pålitligt nativa nästlade ARRAY-, MAP- eller STRUCT-värden som JSON. Omvandla komplexa värden till JSON-strängar i Spark SQL innan du avserialiserar 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);
}

Felsökning

Detta avsnitt ger vägledning för att lösa vanliga problem du kan stöta på när du använder Microsoft ADO.NET Driver for Fabric Data Engineering.

Vanliga problem

I följande avsnitt beskrivs vanliga problem och deras lösningar:

Anslutningsfel

Problem: Kan inte ansluta till Fabric

Lösningar:

1. Verifiera FabricWorkspaceID och FabricLakehouseID är korrekta GUID:er
2. Kontrollera Azure CLI-autentisering: az account show
3. Se till att du har rätt behörigheter för Fabric-arbetsyta
4. Verifiera nätverksanslutningen till api.fabric.microsoft.com

Autentiseringsfel

Problem: Autentiseringen misslyckas med Azure CLI

Lösningar:

• Kör az login för att uppdatera autentiseringsuppgifter
• Verifiera rätt klient: az account set --subscription <subscription-id>
• Kontrollera tokens giltighet: az account get-access-token --resource https://api.fabric.microsoft.com

Timeout för frågor

Problem: Frågor som överskrider tidsgränsen för stora tabeller

Lösningar:

• Öka timeout för instruktion: LivyStatementTimeoutSeconds=1200.
• Använd LIMIT -sats för att begränsa resultatstorleken under utvecklingen
• Se till att Spark-klustret har tillräckliga resurser

Anslutning eller HC-förvärvstidsavbrott

Problem: En anslutning går ut på tiden medan man väntar på en poolad anslutning eller en HC-session

Lösningar:

• För väntetid i klientpoolen och upprättande av HTTP-anslutning, se HttpConnectionTimeoutInSeconds.
• För HC-insamling, öka hcAcquireTimeoutSeconds inom det stödda intervallet 120 till 3 600 sekunder.
• Kontrollera Fabric-kapacitetstillgänglighet
• Kontrollera att arbetsytan inte har nått sessionsgränser

Aktivera loggning

När du felsöker problem kan detaljerad loggning hjälpa dig att identifiera grundorsaken. Konfigurera loggning genom anslutningssträngen:

Så här aktiverar du detaljerad loggning via anslutningssträng:

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

Om du inte ställer in LogFilePath eller en global loggkonfiguration skriver drivrutinen loggar i %LOCALAPPDATA%\FabricSparkAdoNet\Logs på Windows.

Loggnivåer:

• Trace: Mest utförliga, innehåller alla API-anrop
• Debug: Detaljerad felsökningsinformation
• Information: Allmän information (standard)
• Warning: Endast varningar
• Error: Endast fel

Relaterat innehåll

• Apache Spark Runtimes på plattformen
• Fabric-körmiljö 1.3
• Vad är Livy API för datateknik
• Microsoft JDBC-drivrutin för Fabric Data Engineering
• Microsoft ODBC-drivrutin för Fabric Data Engineering