Microsoft ADO.NET drivrutin för Microsoft Fabric Data Engineering (förhandsversion)

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.

Med Microsoft ADO.NET Driver for Fabric Data Engineering kan du ansluta, fråga och hantera Spark-arbetsbelastningar i Microsoft Fabric med tillförlitligheten och enkelheten i standardmönster ADO.NET. Drivrutinen bygger på Livy-API:er i Microsoft Fabric och ger säker och flexibel Spark SQL-anslutning till dina .NET-program med hjälp av välbekanta DbConnection, DbCommandoch DbDataReader abstraktioner.

Viktiga funktioner

• ADO.NET Kompatibel: Fullständig implementering av ADO.NET abstraktioner (DbConnection, , DbCommandDbDataReader, DbParameter, DbProviderFactory)
• 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
• Async Prefetch: Inläsning av bakgrundsdata för bättre prestanda med stora resultatuppsättningar
• Automatisk återanslutning: Automatisk sessionsåterställning efter anslutningsfel

Förutsättningar

Kontrollera att du har följande innan du använder Microsoft ADO.NET Driver för Microsoft Fabric Data Engineering:

• .NET Runtime: .NET 8.0 eller senare
• Microsoft Fabric Access: Åtkomst till en Microsoft Fabric-arbetsyta med funktioner för datateknik
• 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

Microsoft ADO.NET Driver för Microsoft Fabric Data Engineering version 1.0.0 finns i offentlig förhandsversion som du kan ladda ned från dessa länkar i nedladdningscentret.

• Ladda ned Microsoft ADO.NET Driver för Microsoft Fabric Data Engineering (zip)
• Ladda ned Microsoft ADO.NET Driver för Microsoft 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="1.0.0" />
</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/v1;" +
    "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

Loggningsinställningar

Exempel på anslutningssträngar

Grundläggande anslutning (Azure CLI-autentisering)

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

Med alternativ för anslutningspooler

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

Med automatisk återanslutning och loggning

Server=https://api.fabric.microsoft.com/v1;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/v1;" +
    "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/v1;" +
    "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

Klientautentiseringsuppgifter (tjänstens huvudnamn) autentisering

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

string connectionString =
    "Server=https://api.fabric.microsoft.com/v1;" +
    "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/v1;" +
    "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/v1;" +
    "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/v1;" +
    "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($"Inserted {rowsAffected} row(s)");

// UPDATE
using var updateCommand = connection.CreateCommand();
updateCommand.CommandText = "UPDATE employees SET salary = 90000 WHERE id = 100";

rowsAffected = await updateCommand.ExecuteNonQueryAsync();
Console.WriteLine($"Updated {rowsAffected} row(s)");

// DELETE
using var deleteCommand = connection.CreateCommand();
deleteCommand.CommandText = "DELETE FROM employees WHERE id = 100";

rowsAffected = await deleteCommand.ExecuteNonQueryAsync();
Console.WriteLine($"Deleted {rowsAffected} row(s)");

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())
{
    Console.WriteLine($"  {tablesReader.GetString(0)}");
}

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

Använda LivyConnectionStringBuilder

using Microsoft.Spark.Livy.AdoNet;

var builder = new LivyConnectionStringBuilder
{
    Server = "https://api.fabric.microsoft.com/v1",
    SparkServerType = "Fabric",
    FabricWorkspaceID = "<workspace-id>",
    FabricLakehouseID = "<lakehouse-id>",
    AuthFlow = "AzureCli",
    ConnectionPoolingEnabled = true,
    MinPoolSize = 2,
    MaxPoolSize = 10,
    ConnectionTimeout = 60
};

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

Datatypkartläggning

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

Arbeta med komplexa typer

Komplexa typer (ARRAY, MAP, STRUCT) returneras som JSON-strängar som standard:

using System.Text.Json;
using System.Collections.Generic;

using var command = connection.CreateCommand();
command.CommandText = "SELECT array_column, map_column, struct_column FROM complex_table LIMIT 1";

using var reader = await command.ExecuteReaderAsync();
if (await reader.ReadAsync())
{
    // Complex types returned as JSON strings
    string arrayJson = reader.GetString(0);  // e.g., "[1, 2, 3]"
    string mapJson = reader.GetString(1);    // e.g., "{\"key\": \"value\"}"
    string structJson = reader.GetString(2); // e.g., "{\"field1\": 1, \"field2\": \"text\"}"

    // Parse with System.Text.Json
    var array = JsonSerializer.Deserialize<int[]>(arrayJson);
    var map = JsonSerializer.Deserialize<Dictionary<string, string>>(mapJson);
}

Felsökning

Det här avsnittet innehåller vägledning för att lösa vanliga problem som kan uppstå när du använder Microsoft ADO.NET Driver för Microsoft Fabric Data Engineering.

Vanliga problem

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

Anslutningsfel

Problem: Det går inte att ansluta till Microsoft 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 tidsgränsen för instruktionen: LivyStatementTimeoutSeconds=300
• Använd LIMIT -sats för att begränsa resultatstorleken under utvecklingen
• Se till att Spark-klustret har tillräckliga resurser

Tidsgräns för att skapa sessioner

Problem: Tidsgränsen för anslutningen uppnås när sessionen skapas

Lösningar:

• Öka tidsgränsen för sessioner: LivySessionTimeoutSeconds=120
• Kontrollera Fabric-kapacitetstillgänglighet
• Kontrollera att arbetsytan inte har nått sessionsgränser

Aktivera loggning

När du felsöker problem kan du identifiera rotorsaken till problem genom att aktivera detaljerad loggning. Du kan aktivera loggning via anslutningssträngen eller programmatiskt.

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

LogLevel=Debug

Eller konfigurera programmatiskt:

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Debug);
});

// Logging is automatically integrated with the connection

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 Microsoft Fabric Data Engineering
• Microsoft ODBC-drivrutin för Microsoft Fabric Data Engineering