Driver ADO.NET di Microsoft per Microsoft Fabric Data Engineering

ADO.NET è una tecnologia di accesso ai dati ampiamente adottata nell'ecosistema .NET che consente alle applicazioni di connettersi e lavorare con i dati dai database e dalle piattaforme Big Data.

Il driver Microsoft ADO.NET per Fabric Data Engineering ti permette di connettere, interrogare e gestire carichi di lavoro Spark in Fabric con l'affidabilità e la semplicità dei pattern standard ADO.NET. Basato sulle API Livy di Fabric, il driver fornisce alle tue applicazioni .NET una connettività sicura e flessibile a Spark SQL utilizzando le familiari astrazioni DbConnection, DbCommand e DbDataReader.

Funzionalità principali

• API ADO.NET: familiari DbConnection, DbCommand, DbDataReader, DbParameter, e DbProviderFactory astrazioni per la connettività SQL di Spark
• Autenticazione ID Microsoft Entra: più flussi di autenticazione, tra cui l'interfaccia della riga di comando di Azure, browser interattivo, credenziali client, autenticazione basata su certificati e token di accesso
• Supporto per query nativo Spark SQL: Esecuzione diretta di istruzioni Spark SQL con query parametrizzate
• Supporto completo dei tipi di dati: supporto per tutti i tipi di dati SPARK SQL, inclusi tipi complessi (ARRAY, MAP, STRUCT)
• Pool di connessioni: gestione predefinita del pool di connessioni per migliorare le prestazioni
• Riutilizzo sessione: gestione efficiente delle sessioni Spark per ridurre la latenza di avvio
• Sessioni ad alta concorrenza: Opta per la capacità condivisa di Fabric Livy con REPL separati per sessioni HC in affitto simultaneo
• Prelettura asincrona: caricamento dei dati in background per prestazioni migliorate con set di risultati di grandi dimensioni
• Riconnessione automatica: ripristino della sessione classica dopo errori di connessione; gli errori HC vengono segnalati per nuovi tentativi controllati dall'applicazione

Prerequisiti

Prima di utilizzare il driver Microsoft ADO.NET per Fabric Data Engineering, assicurati di avere:

• Runtime .NET: .NET 8.0 o versione successiva
• Fabric Access: Accesso a uno spazio di lavoro Fabric con capacità di Data Engineering
• Azure Entra ID Credentials: credenziali appropriate per l'autenticazione
• ID area di lavoro e Lakehouse: identificatori GUID per il tuo workspace e lakehouse Fabric
• Interfaccia della riga di comando di Azure (facoltativo): obbligatorio per il metodo di autenticazione dell'interfaccia della riga di comando di Azure

Scaricare, includere, fare riferimento e verificare

Scaricare il pacchetto NuGet

• Scarica il driver Microsoft ADO.NET per Fabric Data Engineering (zip)
• Scarica il driver Microsoft ADO.NET per Fabric Data Engineering (tar)

Fare riferimento al pacchetto NuGet nel progetto

Includere il pacchetto NuGet scaricato nel progetto e aggiungere un riferimento del pacchetto al file di progetto:

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

Verifica l'installazione

Dopo l'inclusione e il riferimento, verificare che il pacchetto sia disponibile nel progetto:

using Microsoft.Spark.Livy.AdoNet;

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

Esempio di avvio rapido

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

Formato della stringa di connessione

Formato di base

Microsoft ADO.NET Driver usa il formato della stringa di connessione standard ADO.NET:

Parameter1=Value1;Parameter2=Value2;...

Parametri obbligatori

Parametri facoltativi

Impostazioni di connessione

Impostazioni del pool di connessioni

Impostazioni di concorrenza elevate

Impostazioni di registrazione

Alias tra driver: Il driver accetta nomi di proprietà JDBC e ODBC oltre a nomi nativi ADO.NET (ad esempio, WorkspaceId viene mappato su FabricWorkspaceID, LakehouseId viene mappato su FabricLakehouseID). Tutti i nomi delle proprietà sono insensibili alla distinzione tra maiuscole e minuscole.

Esempi di stringhe di connessione

Connessione di base (autenticazione dell'interfaccia della riga di comando di Azure)

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

Connessione ad alta simultaneità

È disponibile un'alta concorrenza per le connessioni Microsoft Fabric. Imposta HcEnabled=true; le API standard di connessione ADO.NET e comando rimangono invariate. Usa l'host API Fabric non versionato per Server; il driver usa FabricVersion=v1 e LivyApiVersion=2023-12-01 di default quando compila l'endpoint HC.

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

Per indicazioni complete sulla configurazione, consulta la sezione Modalità a elevata concorrenza (HC).

Con le opzioni di pool di connessioni

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

Con la riconnessione automatica e la registrazione

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

Autenticazione

Microsoft ADO.NET Driver supporta più metodi di autenticazione tramite Microsoft Entra ID (in precedenza Azure Active Directory). L'autenticazione viene configurata usando il AuthFlow parametro nella stringa di connessione.

Metodi di autenticazione

Autenticazione dell’interfaccia della riga di comando di Azure

Ideale per: sviluppo e test

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:

• Interfaccia della riga di comando di Azure installata: az --version
• Autenticato: az login

Autenticazione interattiva del browser

Ideale per: applicazioni rivolte agli utenti

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

Comportamento:

• Apre una finestra del browser per l'autenticazione utente
• Le credenziali vengono memorizzate nella cache per le connessioni successive

Autenticazione delle credenziali del client (principale del servizio)

Ideale per: servizi automatizzati e processi in background

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

Parametri obbligatori:

• AuthTenantID: ID tenant di Azure
• AuthClientID: ID dell'applicazione (client) di Microsoft Entra ID
• AuthClientSecret: segreto del client da Microsoft Entra ID

Autenticazione basata su certificati

Ideale per: applicazioni aziendali che richiedono l'autenticazione basata su certificati

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

Parametri obbligatori:

• AuthTenantID: ID tenant di Azure
• AuthClientID: ID applicazione (cliente)
• AuthCertificatePath: percorso del file di certificato PFX/PKCS12
• AuthCertificatePassword: password del certificato

Autenticazione del token di accesso

Ideale per: scenari di autenticazione personalizzati

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

Esempi di utilizzo

Query e connessione di base

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

Query con parametri

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 per valori unici

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

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

ExecuteNonQuery per le operazioni DML

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

Utilizzo di set di risultati di grandi dimensioni

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

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

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

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

Modalità ad alta concorrenza (HC)

La modalità ad alta concorrenza (HC) aiuta le applicazioni .NET a eseguire carichi di lavoro SQL Spark simultanei senza fornire una sessione Spark classica separata per ogni connessione ADO.NET. Fabric possono inserire connessioni compatibili nella stessa sessione Livy gestita dal server, fornendo a ciascuna connessione un Read-Eval-Print Loop (REPL) isolato per l'esecuzione delle istruzioni.

Questo modello può ridurre i tempi di avvio della connessione, evitare il provisioning ripetuto delle sessioni Spark e utilizzare la capacità di Fabric Spark in modo più efficiente. La tua applicazione continua a utilizzare API standard ADO.NET, tra cui DbConnection, DbCommand, DbDataReader, OpenAsync, e Close.

La modalità HC è facoltativa. Se non lo abiliti, il driver usa il percorso classico della sessione di Livy.

Scegli tra modalità HC e classica

Usa la modalità HC quando:

• Un servizio ASP.NET gestisce richieste concorrenti che aprono connessioni ed esegue Spark SQL.
• Un servizio di lavoro, un lavoro programmato o una pipeline dati parallela crea raffiche di connessioni ADO.NET.
• Più connessioni mirano allo stesso spazio di lavoro Fabric e allo stesso lakehouse e utilizzano configurazioni Spark compatibili.
• Ridurre i tempi di avvio della connessione e il provisioning ripetuto delle sessioni Spark è importante.
• Il tuo carico di lavoro può utilizzare la capacità Spark condivisa e gestita dal server, mantenendo l'esecuzione degli istruzioni isolata dal REPL.

Usa la modalità classica quando:

• La tua applicazione utilizza solo una o poche connessioni durature.
• Ogni connessione richiede una sessione Spark dedicata per un carico di lavoro rigoroso o per l'isolamento delle risorse.
• Le connessioni richiedono configurazioni Spark sostanzialmente diverse che non dovrebbero condividere una sessione sottostante.
• L'endpoint Fabric Livy per lo spazio di lavoro target e lakehouse non supporta la modalità HC.

Come funzionano le connessioni HC

Quando l'applicazione chiama Open o OpenAsync e non è disponibile una connessione in pool compatibile, il driver:

1. Richiede una sessione HC a Fabric.
2. Attende che la sessione diventi pronta, per un massimo pari al timeout di acquisizione configurato.
3. Collega la connessione ADO.NET alla sessione HC assegnata e al REPL.
4. Instrada comandi, interrogative, richieste di cancellazione e operazioni di pulizia attraverso gli endpoint HC.

Le sessioni HC separate in affitto simultaneo utilizzano REPL separati. I comandi su una connessione condividono la sessione HC e il REPL di quella connessione.

Il pooling lato client è abilitato di default. Chiudere o eliminare una connessione idonea normalmente restituisce la sessione HC fisica e il REPL al pool locale del processo per il riutilizzo; non necessariamente rilascia l'assegnazione da remoto. Con il pooling disabilitato, la chiusura della connessione fisica esegue la pulizia di HC. Continua a usare le istruzioni using affinché i collegamenti logici vengano restituiti tempestivamente.

Abilita modalità HC

La modalità HC è facoltativa. Se ometti hcEnabled o lo imposti su false, il driver usa il percorso classico della sessione Livy.

Imposta la proprietà hcEnabled su vera per acquisire una sessione HC:

hcEnabled=true;

Configura il raggruppamento delle sessioni

HcSessionTag fornisce un'indicazione lato server per raggruppare sessioni HC compatibili in una sessione Livy di base. Un tag corrispondente non garantisce la collocazione nella stessa sessione sottostante.

Se ometti il tag o fornisci un valore vuoto o solo spazio bianco, il driver non lo invia nella richiesta di acquisizione. L'omissione del tag non disabilita la modalità HC né l'impacchettamento lato servizio. Imposta un tag esplicito quando istanze o carichi di lavoro applicativi correlati devono essere considerati per capacità condivisa. Usa un'etichetta operativa stabile e non sensibile, come reporting-service o nightly-etl. Non includere segreti, token di accesso, dati personali, identificatori dei clienti o testi di richiesta.

La configurazione di Spark influisce anche sulla compatibilità della sessione. Usa HcConfOverrides per fornire le impostazioni Spark consentite per creare sessioni HC:

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

Per più sostituzioni, racchiudi tra virgolette l'intero valore HcConfOverrides. Un punto e virgola senza virgolette avvia un'altra proprietà esterna della stringa di connessione; non estende HcConfOverrides. Il parser accetta valori a virgolette singole o doppie, conserva punti e virgola e segni uguali all'interno dei valori tra virgolette, e decodifica virgolette doppie corrispondenti ('' o ""). Lo spazio bianco intorno ai nomi delle proprietà e ai margini esterni dei valori non citati viene ignorato. Lo spazio bianco all'interno dei valori non quotati e tutto lo spazio all'interno dei valori tra virgolette viene preservato. I valori vuoti sovrascrivono i valori predefiniti dell'ambiente, e vince l'ultima proprietà duplicata.

Puoi anche lasciare LivyConnectionStringBuilder che ti occupi delle citazioni:

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;

Questi esempi richiedono il driver Microsoft ADO.NET versione 2.0.1 o successiva. Aggiungi gli identificatori dello spazio di lavoro e del lago prima di aprire una connessione. Entrambi gli override vengono inviati nella richiesta HC create-session come elementi separati conf. Ogni sovrascrittura deve utilizzare una di queste chiavi con distinzione tra maiuscole e minuscole:

• 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

Le virgolette malformate vengono rifiutate senza includere i contenuti della stringa di connessione nell'errore di analisi.

Usa tag e valori di configurazione coerenti tra le connessioni che sono pensate per condividere la capacità. Fabric determina se una richiesta può utilizzare una sessione esistente o richiede un'altra sessione.

Configurare i tempi di acquisizione

Usa le seguenti impostazioni per controllare quanto tempo il driver aspetta una sessione HC:

Per la maggior parte dei carichi di lavoro, mantenere i valori predefiniti. Aumenta il timeout per l'acquisizione solo quando l'avvio della capacità richiede regolarmente più di cinque minuti.

Usa la modalità HC con il pool di connessioni

La modalità HC e il pooling delle connessioni di ADO.NET operano a livelli diversi:

• La modalità HC gestisce la capacità condivisa di Fabric Spark e le sessioni Livy sul server.
• Il pool di connessioni ADO.NET riutilizza risorse di connessione gestite dal driver nell'applicazione client.

Puoi abilitare entrambe le funzioni. Il pool di connessioni riduce la creazione ripetuta delle connessioni lato client, mentre la modalità HC riduce il provisioning ripetuto delle sessioni Spark lato server. Dimensionare il pool di connessione per la concorrenza prevista dell'applicazione invece di usare un pool grande per creare lavoro parallelo inutile.

In modalità HC, AutoReconnect=true non riproduce trasparentemente un comando fallito dopo un errore di sessione obsoleta. L'applicazione riceve l'eccezione e deve decidere se è sicuro riprovare l'operazione.

Disabilita la modalità HC

Per usare la modalità classica per nuove connessioni, rimuovi HcEnabled dalla stringa di connessione o impostala su false:

HcEnabled=false

La modifica si applica alle nuove connessioni e non svuota le sessioni HC già presenti nel pool. Chiudere o eliminare normalmente le connessioni logiche; le sessioni fisiche idonee possono rimanere nel pool clienti fino al loro ritiro.

limitazioni ADO.NET

• Le transazioni non sono supportate.
• I comandi supportano solo la modalità comando testuale. Le modalità di comando stored-procedure e le modalità table-direct non sono supportate.
• Prepare Non fa nulla.
• Un comando deve contenere una sola istruzione; il testo del comando multi-istruzioni viene rifiutato.
• Usa connessioni separate e contemporaneamente aperte per carichi di lavoro concorrenti. I comandi in una connessione condividono la stessa sessione e il REPL.

Mappatura del tipo di dati

Il driver esegue il mapping dei tipi di dati Spark SQL ai tipi .NET:

Lavorare con tipi complessi

Il percorso di risultato HC non serializza in modo affidabile i valori nativi annidati di ARRAY, MAP o STRUCT come JSON. Proiettare i valori complessi come stringhe JSON in Spark SQL prima di deserializzarli:

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

Risoluzione dei problemi

Questa sezione fornisce indicazioni per risolvere problemi comuni che potresti incontrare utilizzando il driver Microsoft ADO.NET per Fabric Data Engineering.

Problemi comuni

Le sezioni seguenti descrivono i problemi comuni e le relative soluzioni:

Errori di connessione

Problema: Non riesco a collegarsi a Fabric

Soluzioni:

1. Verificare che FabricWorkspaceID e FabricLakehouseID siano GUID corretti
2. Controllare l'autenticazione della CLI di Azure: az account show
3. Assicurati di possedere le autorizzazioni appropriate per l'area di lavoro Fabric.
4. Verificare la connettività di rete a api.fabric.microsoft.com

Errori di autenticazione

Problema: l'autenticazione non riesce con l'interfaccia della riga di comando di Azure

Soluzioni:

• Eseguire az login per aggiornare le credenziali
• Verificare il tenant corretto: az account set --subscription <subscription-id>
• Controllare la validità del token: az account get-access-token --resource https://api.fabric.microsoft.com

Timeout query

Problema: timeout delle query su tabelle di grandi dimensioni

Soluzioni:

• Aumenta il timeout dell'istruzione: LivyStatementTimeoutSeconds=1200.
• Utilizzare la clausola LIMIT per limitare le dimensioni dei risultati durante lo sviluppo
• Verificare che il cluster Spark disponga di risorse adeguate

Time out per connessione o acquisizione HC

Problema: Una connessione scadde mentre aspetta una connessione in pool o una sessione HC

Soluzioni:

• Per l'attesa del pool di client e la creazione della connessione HTTP, consulta HttpConnectionTimeoutInSeconds.
• Per l'acquisizione di HC, aumentare hcAcquireTimeoutSeconds entro l'intervallo supportato compreso tra 120 e 3.600 secondi.
• Controllare la disponibilità della capacità del Fabric
• Verificare che l'area di lavoro non abbia raggiunto i limiti di sessione

Abilitare la registrazione

Quando si risolvono problemi, una registrazione dettagliata può aiutarti a identificare la causa principale. Configura la registrazione tramite la stringa di connessione:

Per abilitare la registrazione dettagliata tramite la stringa di connessione:

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

Se non imposti LogFilePath o non imposti una configurazione di logging globale, il driver scrive i log su %LOCALAPPDATA%\FabricSparkAdoNet\Logs Windows.

Livelli di log:

• Trace: livello di massima verbosità, include tutte le chiamate API
• Debug: informazioni dettagliate sul debug
• Information: informazioni generali (impostazione predefinita)
• Warning: Solo avvertimenti
• Error: solo errori

Contenuti correlati

• Runtime di Apache Spark in Fabric
• Runtime Fabric 1.3
• Informazioni sull'API Livy per ingegneria dei dati
• Microsoft JDBC Driver per Fabric Data Engineering
• Driver Microsoft ODBC per Fabric Data Engineering