Pilote Microsoft ADO.NET pour Microsoft Fabric Ingénierie des données

ADO.NET est une technologie d’accès aux données largement adoptée dans l’écosystème .NET qui permet aux applications de se connecter et d’utiliser des données à partir de bases de données et de plateformes Big Data.

Le pilote Microsoft ADO.NET pour l’ingénierie des données Fabric vous permet de connecter, interroger et gérer des charges de travail Spark dans Fabric avec la fiabilité et la simplicité des patrons ADO.NET standards. Basé sur les API Livy de Fabric, le pilote offre une connectivité sécurisée et flexible à Spark SQL pour vos applications .NET à l’aide des abstractions familières DbConnection, DbCommand et DbDataReader.

Fonctionnalités clés

• API ADO.NET : abstractions familières DbConnection, DbCommand, DbDataReader, DbParameter et DbProviderFactory pour la connectivité à Spark SQL
• Authentification d’ID Microsoft Entra : plusieurs flux d’authentification, notamment Azure CLI, navigateur interactif, informations d’identification du client, authentification par certificat et jeton d’accès
• Prise en charge des requêtes natives Spark SQL : exécution directe d’instructions Spark SQL avec des requêtes paramétrables
• Prise en charge complète des types de données : prise en charge de tous les types de données Spark SQL, y compris les types complexes (ARRAY, MAP, STRUCT)
• Regroupement de connexions : gestion intégrée du pool de connexions pour améliorer les performances
• Réutilisation de session : Gestion efficace des sessions Spark pour réduire la latence de démarrage
• Sessions à forte concurrence : Optez pour une capacité partagée Fabric Livy avec des REPL séparés pour des sessions HC louées simultanément
• Prérécupération asynchrone : chargement des données en arrière-plan pour améliorer les performances avec des jeux de résultats volumineux
• Reconnexion automatique : récupération classique après défaillance de connexion ; Les défaillances HC sont mises en avant pour les réessais contrôlés par l’application

Prerequisites

Avant d’utiliser le pilote Microsoft ADO.NET pour Fabric Data Engineering, assurez-vous d’avoir :

• Runtime .NET : .NET 8.0 ou version ultérieure
• Fabric Access : Accès à un espace de travail Fabric avec des capacités d’ingénierie des données
• Informations d’identification d’ID Azure Entra : informations d’identification appropriées pour l’authentification
• Identifiants d’espace de travail et de Lakehouse : identificateurs GUID pour votre espace de travail Fabric et votre Lakehouse.
• Azure CLI (facultatif) : obligatoire pour la méthode d’authentification Azure CLI

Télécharger, inclure, référencer et vérifier

Télécharger le package NuGet

• Téléchargez le pilote Microsoft ADO.NET pour Fabric Data Engineering (zip)
• Téléchargez le pilote Microsoft ADO.NET pour Fabric Data Engineering (tar)

Référencer le package NuGet dans votre projet

Incluez le package NuGet téléchargé dans votre projet et ajoutez une référence du package à votre fichier projet :

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

Vérifier l’installation

Après l’inclusion et la référence, vérifiez que le package est disponible dans votre projet :

using Microsoft.Spark.Livy.AdoNet;

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

Exemple de démarrage rapide

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 de la chaîne de connexion

Format de base

Microsoft ADO.NET Driver utilise le format de chaîne de connexion standard ADO.NET :

Parameter1=Value1;Parameter2=Value2;...

Paramètres obligatoires

Paramètres facultatifs

Paramètres de connexion

Paramètres du pool de connexions

Réglages de concurrence élevée

Paramètres de journalisation

Alias inter-pilotes : Le pilote accepte les noms de propriétés JDBC et ODBC en plus des noms de ADO.NET natifs (par exemple, WorkspaceId mappe à FabricWorkspaceID, LakehouseId mappe à FabricLakehouseID). Tous les noms de propriétés sont insensibles à la casse.

Exemples de chaîne de connexion

Connexion de base (authentification Azure CLI)

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

Connexion à forte concurrence

Une forte concurrence est disponible pour les connexions Microsoft Fabric. Définissez HcEnabled=true; les API standard de connexion et de commande ADO.NET restent inchangées. Utilisez l’hôte API Fabric non versionné pour Server; le pilote utilise FabricVersion=v1 et LivyApiVersion=2023-12-01 par défaut lorsqu’il construit le point de terminaison 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}");

Pour des instructions complètes de configuration, consultez la section Mode haute concurrence (HC).

Avec les options de regroupement de connexions

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

Avec la reconnexion automatique et la journalisation

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

Authentification

Microsoft ADO.NET Driver prend en charge plusieurs méthodes d’authentification via Microsoft Entra ID (anciennement Azure Active Directory). L’authentification est configurée à l’aide du AuthFlow paramètre dans la chaîne de connexion.

Méthodes d’authentification

L'authentification de l'Azure CLI

Idéal pour : développement et 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();

Conditions préalables :

• Azure CLI installé : az --version
• Connecté : az login

Authentification interactive du navigateur

Idéal pour : applications accessibles par l’utilisateur

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

Comportement :

• Ouvre une fenêtre de navigateur pour l’authentification utilisateur
• Les informations d’identification sont mises en cache pour les connexions suivantes

Authentification des informations d’identification du client (principal de service)

Idéal pour : services automatisés et travaux en arrière-plan

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

Paramètres obligatoires :

• AuthTenantID: ID de locataire Azure
• AuthClientID: ID d’application (client) de Microsoft Entra ID
• AuthClientSecret: Secret client de l'ID Microsoft Entra

Authentification basée sur un certificat

Idéal pour : les applications d’entreprise nécessitant une authentification basée sur des certificats

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

Paramètres obligatoires :

• AuthTenantID: ID de locataire Azure
• AuthClientID: ID d’application (client)
• AuthCertificatePath: chemin d’accès au fichier de certificat PFX/PKCS12
• AuthCertificatePassword: Mot de passe du certificat

Authentification par jeton d’accès

Idéal pour : scénarios d’authentification personnalisés

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

Exemples d’utilisation

Connexion et requête de 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();
}

Requêtes paramétrables

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 pour les valeurs uniques

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

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

ExecuteNonQuery pour les opérations 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.");

Utilisation de jeux de résultats volumineux

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

Découverte de schéma

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

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

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

Mode haute concurrence (HC)

Le mode haute concurrence (HC) aide les applications .NET à exécuter des charges de travail SQL Spark simultanées sans provisionner une session Spark classique distincte pour chaque connexion ADO.NET. Fabric peut placer des connexions compatibles dans la même session Livy gérée par le serveur tout en fournissant à chaque connexion une boucle isolée de lectureEval-Print (REPL) pour l’exécution des instructions.

Ce modèle peut réduire le temps de démarrage de la connexion, éviter la provisionnement répétée des sessions Spark et utiliser la capacité de Fabric Spark de manière plus efficace. Votre application continue d’utiliser les API standard ADO.NET, notamment DbConnection, DbCommand, DbDataReader, OpenAsync, et Close.

Le mode HC doit être activé manuellement. Si vous ne l’activez pas, le pilote utilise le chemin classique de la session Livy.

Choisissez entre le mode HC et le mode classique

Utilisez le mode HC lorsque :

• Un service ASP.NET gère les requêtes concurrentes qui ouvrent des connexions et exécutent Spark SQL.
• Un service de travail, un travail planifié ou un pipeline de données parallèle crée des rafales de connexions ADO.NET.
• Plusieurs connexions ciblent le même espace de travail Fabric et le même lakehouse et utilisent des configurations compatibles avec Spark.
• Réduire le temps de démarrage de la connexion et le provisionnement répété des sessions Spark est important.
• Votre charge de travail peut utiliser une capacité Spark partagée et gérée par le serveur tout en maintenant l’exécution des instructions isolée par le REPL.

Utilisez le mode classique lorsque :

• Votre application n’utilise qu’une ou quelques connexions durables.
• Chaque connexion nécessite une session Spark dédiée pour une charge de travail stricte ou une isolation des ressources.
• Les connexions nécessitent des configurations Spark sensiblement différentes qui ne devraient pas partager une session sous-jacente.
• Le point de terminaison Livy de Fabric pour l’espace de travail cible et le lakehouse ne prend pas en charge le mode HC.

Comment fonctionnent les connexions HC

Lorsque votre application appelle Open ou OpenAsync qu’aucune connexion poolée compatible n’est disponible, le pilote :

1. Demande une session HC à Fabric.
2. Attend que la session soit prête, dans la limite du délai d’acquisition configuré.
3. Connecte la connexion ADO.NET à la session HC assignée et au REPL.
4. Achemine les commandes, les requêtes, les demandes d’annulation et les opérations de nettoyage via les points de terminaison HC.

Les sessions HC louées séparément et simultanément utilisent des REPL distincts. Les commandes exécutées via une connexion partagent la session HC et le REPL associés à cette connexion.

Le pooling côté client est activé par défaut. La fermeture ou la suppression d’une connexion éligible renvoie normalement sa session HC physique et son REPL au pool local de processus pour réutilisation ; cela ne libère pas nécessairement l’attribution à distance. Avec le pooling désactivé, fermer la connexion physique effectue le nettoyage HC. Continuez à utiliser des instructions using afin que les liens logiques s’établissent rapidement.

Activer le mode HC

Le mode HC doit être activé manuellement. Si vous omettez hcEnabled ou le définissez sur false, le pilote utilise le chemin de session Livy classique.

Réglez la propriété hcEnabled sur true pour acquérir une session HC :

hcEnabled=true;

Configurer le package de session

HcSessionTag fournit un indice côté serveur pour intégrer des sessions HC compatibles dans une session Livy sous-jacente. Un tag correspondant ne garantit pas le placement dans la même session de base.

Si vous omettez l’étiquette ou fournissez une valeur vide ou ne contenant que des espaces, le pilote ne l’envoie pas dans la requête d’acquisition. Omettre l’étiquette ne désactive pas le mode HC ni l’emballage côté service. Définir un tag explicite lorsque des instances ou charges de travail liées doivent être prises en compte pour la capacité partagée. Utilisez une étiquette opérationnelle stable et non sensible, telle que reporting-service ou nightly-etl. N’incluez pas de secrets, de jetons d’accès, de données personnelles, d’identifiants clients ou de textes de requête.

La configuration de Spark affecte également la compatibilité des sessions. Utilisez HcConfOverrides pour fournir les paramètres Spark sur liste autorisée pour la création d’une session HC :

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

Pour plusieurs overrides, indiquez la valeur totale HcConfOverrides . Un point-virgule sans guillemets commence une autre propriété externe de chaîne de connexion ; il ne s’étend pas à HcConfOverrides. L’analyseur accepte les valeurs entre guillemets simples ou doubles, conserve les signes de point-virgule et d’égal à l’intérieur des valeurs entre guillemets, et décode les guillemets doubles correspondants ('' ou ""). Les espaces blancs autour des noms de propriétés et aux bords extérieurs des valeurs non guillemets sont ignorés. Les espaces blancs à l’intérieur des valeurs non guillemets et tous les espaces à l’intérieur des valeurs entre guillemets sont préservés. Les valeurs vides supplantent les paramètres par défaut de l’environnement, et la dernière propriété dupliquée l’emporte.

Vous pouvez aussi laisser LivyConnectionStringBuilder gérer les citations :

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;

Ces exemples nécessitent le pilote Microsoft ADO.NET version 2.0.1 ou ultérieure. Ajoutez les identifiants de votre espace de travail et de votre lakehouse avant d’ouvrir une connexion. Les deux substitutions sont envoyées dans la requête create-session de HC sous forme d’entrées conf distinctes. Chaque dérogation doit utiliser l’une de ces clés sensibles à la majuscule :

• 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

Les guillemets mal formés sont rejetés sans inclure le contenu de la chaîne de connexion dans l’erreur d’analyse syntaxique.

Utilisez des tags et des valeurs de configuration cohérents entre les connexions destinées à partager la capacité. Fabric détermine si une requête peut utiliser une session existante ou nécessite une autre session.

Configurer la temporisation d’acquisition

Utilisez les réglages suivants pour contrôler combien de temps le pilote attend une session HC :

Pour la plupart des charges de travail, gardez les valeurs par défaut. Augmentez le délai d’acquisition uniquement lorsque le démarrage de capacité prend régulièrement plus de cinq minutes.

Utilisez le mode HC avec le pooling de connexions

Le mode HC et le pooling de connexions ADO.NET abordent différentes couches :

• Le mode HC gère la capacité partagée de Fabric Spark et les sessions Livy sur le serveur.
• Le pooling de connexions ADO.NET réutilise les ressources de connexion gérées par le pilote dans l’application client.

Vous pouvez activer les deux fonctionnalités. Le pooling de connexions réduit la configuration répétée de la connexion côté client, tandis que le mode HC réduit la provisionnement répété des sessions Spark côté serveur. Dimensionner le pool de connexions pour la concurrence attendue de l’application au lieu d’utiliser un grand pool pour créer un travail parallèle inutile.

En mode HC, AutoReconnect=true ne relance pas automatiquement une commande ayant échoué après une erreur de session obsolète. La demande reçoit l’exception et doit décider si la nouvelle tentative est sûre.

Désactiver le mode HC

Pour utiliser le mode classique pour les nouvelles connexions, retirez HcEnabled de la chaîne de connexion ou réglez-la sur false:

HcEnabled=false

Ce changement affecte les nouvelles connexions et ne vide pas les sessions HC poolées existantes. Fermez ou libérez normalement les connexions logiques ; les sessions physiques éligibles peuvent rester dans le pool de connexions côté client jusqu’à leur mise hors service.

limitations de ADO.NET

• Les transactions ne sont pas prises en charge.
• Les commandes ne prennent en charge que le mode commande textuelle. Les modes de commande à procédure stockée et à table directe ne sont pas pris en charge.
• Prepare ne fait rien.
• Une commande doit contenir une instruction ; le texte de la commande multi-instructions est rejeté.
• Utilisez des connexions séparées et ouvertes simultanément pour des charges de travail concurrentes. Les commandes exécutées via une même connexion partagent la session et le REPL associés.

Mappage de types de données

Le pilote mappe les types de données Spark SQL aux types .NET :

Utilisation de types complexes

Le chemin de résultat HC ne sérialise pas de manière fiable les valeurs natives imbriquées ARRAY, MAP ou STRUCT sous forme de JSON. Convertir des valeurs complexes en chaînes de caractères JSON dans Spark SQL avant de les désérialiser :

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

Résolution des problèmes

Cette section fournit des conseils pour résoudre les problèmes courants que vous pourriez rencontrer en utilisant le pilote Microsoft ADO.NET pour l’ingénierie des données Fabric.

Problèmes courants

Les sections suivantes décrivent les problèmes courants et leurs solutions :

Échecs de connexion

Problème : impossible de se connecter à Fabric

Solutions :

1. Vérifiez que FabricWorkspaceID et FabricLakehouseID sont des GUID corrects
2. Vérifiez l’authentification Azure CLI : az account show
3. Vérifiez que vous disposez des autorisations appropriées pour l’espace de travail Fabric
4. Vérifier la connectivité réseau à api.fabric.microsoft.com

Erreurs d’authentification

Problème : l’authentification échoue avec Azure CLI

Solutions :

• Exécuter az login pour actualiser les informations d’identification
• Vérifiez le locataire correct : az account set --subscription <subscription-id>
• Vérifiez la validité du jeton : az account get-access-token --resource https://api.fabric.microsoft.com

Délais d’expiration des requêtes

Problème : Les requêtes expirent sur des tables volumineuses

Solutions :

• Augmenter le délai d’expiration des relevés : LivyStatementTimeoutSeconds=1200.
• Utilisez la clause LIMIT pour restreindre la taille des résultats pendant le développement
• Vérifier que le cluster Spark dispose de ressources adéquates

Délai d’attente pour la connexion ou l’acquisition de HC

Problème : Une connexion expire en attendant une connexion regroupée ou une session HC

Solutions :

• Pour l’attente du pool de clients et l’établissement de la connexion HTTP, consultez HttpConnectionTimeoutInSeconds.
• Pour l’acquisition de HC, augmentez hcAcquireTimeoutSeconds dans la plage prise en charge de 120 à 3 600 secondes.
• Vérifier la disponibilité de la capacité fabric
• Vérifier que l’espace de travail n’a pas atteint les limites de session

Activation de la journalisation

Lors du dépannage, une journalisation détaillée peut vous aider à identifier la cause profonde. Configurez la journalisation via la chaîne de connexion :

Pour activer la journalisation détaillée via la chaîne de connexion :

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

Si vous ne définissez pas LogFilePath ou une configuration de journalisation globale, le pilote écrit des journaux dans %LOCALAPPDATA%\FabricSparkAdoNet\Logs sous Windows.

Niveaux de journalisation :

• Trace: La plus détaillée, inclut tous les appels d'API
• Debug: Informations de débogage détaillées
• Information: Informations générales (par défaut)
• Warning: Avertissements uniquement
• Error: erreurs uniquement

Contenu connexe

• Environnements d'exécution Apache Spark dans Fabric
• Fabric Runtime 1.3
• Présentation de l’API Livy pour l’ingénierie des données
• Microsoft JDBC Driver for Fabric Data Engineering
• Pilote Microsoft ODBC pour l’ingénierie des données Fabric