Microsoft ADO.NET-stuurprogramma voor Microsoft Fabric Data Engineering (preview)

ADO.NET is een veelgebruikte technologie voor gegevenstoegang in het .NET-ecosysteem waarmee toepassingen verbinding kunnen maken met en kunnen werken met gegevens uit databases en big data-platforms.

Met het Microsoft ADO.NET Driver for Fabric Data Engineering kunt u Spark-workloads in Microsoft Fabric verbinden, opvragen en beheren met de betrouwbaarheid en eenvoud van standaard ADO.NET patronen. Het stuurprogramma is gebouwd op de Livy-API's van Microsoft Fabric en biedt veilige en flexibele Spark SQL-connectiviteit met uw .NET-toepassingen met behulp van vertrouwde DbConnection, DbCommanden DbDataReader abstracties.

Belangrijkste kenmerken

• ADO.NET Compatibel: Volledige implementatie van ADO.NET abstracties (DbConnection, DbCommand, DbDataReader, DbParameter, DbProviderFactory)
• Microsoft Entra ID-verificatie: meerdere verificatiestromen, waaronder Azure CLI, interactieve browser, clientreferenties, verificatie op basis van certificaten en toegangstokenverificatie
• Ondersteuning voor systeemeigen Spark SQL-query's: Directe uitvoering van Spark SQL-instructies met geparameteriseerde query's
• Uitgebreide ondersteuning voor gegevenstypen: ondersteuning voor alle Spark SQL-gegevenstypen, waaronder complexe typen (ARRAY, MAP, STRUCT)
• Groepsgewijze verbindingen: ingebouwd beheer van verbindingsgroepen voor verbeterde prestaties
• Sessie opnieuw gebruiken: Efficiënt Spark-sessiebeheer om de opstartlatentie te verminderen
• Asynchrone prefetch: achtergrondgegevens laden voor verbeterde prestaties met grote resultatensets
• Automatisch opnieuw verbinding maken: Automatisch sessieherstel na verbindingsfouten

Vereiste voorwaarden

Voordat u het Microsoft ADO.NET-stuurprogramma voor Microsoft Fabric Data Engineering gebruikt, moet u het volgende doen:

• .NET Runtime: .NET 8.0 of hoger
• Microsoft Fabric Access: Toegang tot een Microsoft Fabric-werkruimte met mogelijkheden voor data engineering
• Referenties voor Azure Entra ID: juiste referenties voor authenticatie
• Werkruimte- en Lakehouse-id's: GUID-id's voor uw Fabric-werkruimte en Lakehouse
• Azure CLI (optioneel): vereist voor azure CLI-verificatiemethode

Downloaden, opnemen, verwijzen en verifiëren

NuGet-pakket downloaden

Microsoft ADO.NET Driver voor Microsoft Fabric Data Engineering is in versie 1.0.0 als publieke preview beschikbaar die u kunt downloaden via deze downloadcentrum links.

• Microsoft ADO.NET-stuurprogramma voor Microsoft Fabric Data Engineering (zip) downloaden
• Microsoft ADO.NET-stuurprogramma voor Microsoft Fabric Data Engineering (tar) downloaden

Neem het NuGet-pakket op in uw project

Neem het gedownloade NuGet-pakket op in uw project en voeg een verwijzing van het pakket toe aan uw projectbestand:

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

Installatie controleren

Controleer na opname en verwijzing of het pakket beschikbaar is in uw project:

using Microsoft.Spark.Livy.AdoNet;

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

Snelstartvoorbeeld

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

Indeling van verbindingstekenreeks

Basisindeling

Het Microsoft ADO.NET-stuurprogramma maakt gebruik van de standaardindeling voor ADO.NET verbindingsreeks:

Parameter1=Value1;Parameter2=Value2;...

Benodigde parameters

Optionele parameters

Verbindingsinstellingen

Instellingen voor verbindingsgroep

Instellingen voor logboekregistratie

Voorbeeld van verbindingsreeksen

Basisverbinding (Azure CLI-verificatie)

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

Met opties voor groepsgewijze verbindingen

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

Met automatisch opnieuw verbinden en logboekregistratie

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

Authentication

Het Microsoft ADO.NET-stuurprogramma ondersteunt meerdere verificatiemethoden via Microsoft Entra ID (voorheen Azure Active Directory). Verificatie wordt geconfigureerd met behulp van de AuthFlow parameter in de verbindingsreeks.

Verificatiemethoden

Azure CLI-verificatie

Geschikt voor: Ontwikkeling en testen

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

vereisten:

• Azure CLI geïnstalleerd: az --version
• Ingelogd: az login

Interactieve browserverificatie

Geschikt voor: gebruikersgerichte toepassingen

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

Gedrag:

• Hiermee opent u een browservenster voor gebruikersverificatie
• Referenties worden in de cache opgeslagen voor volgende verbindingen

Verificatie van clientreferenties (service-principal)

Geschikt voor: Geautomatiseerde services en achtergrondtaken

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

Vereiste parameters:

• AuthTenantID: Azure-tenant-id
• AuthClientID: Toepassings-ID (client) van Microsoft Entra ID
• AuthClientSecret: Clientgeheim van Microsoft Entra-id

Verificatie op basis van certificaat

Geschikt voor: Bedrijfstoepassingen waarvoor verificatie op basis van certificaten is vereist

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

Vereiste parameters:

• AuthTenantID: Azure-tenant-id
• AuthClientID: Applicatie-ID (client)
• AuthCertificatePath: Pad naar PFX-/PKCS12-certificaatbestand
• AuthCertificatePassword: Certificaatwachtwoord

Verificatie van toegangstokens

Geschikt voor: Scenario's voor aangepaste verificatie

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

Voorbeelden van gebruik

Eenvoudige verbinding en opvraging

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

Geparameteriseerde query's

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 voor enkele waarden

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

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

ExecuteNonQuery voor DML-bewerkingen

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

Werken met grote resultatensets

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

Schema-ontdekking

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

LivyConnectionStringBuilder gebruiken

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

DbProviderFactory gebruiken

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

Koppeling van gegevenstypen

Het stuurprogramma wijst Spark SQL-gegevenstypen toe aan .NET-typen:

Werken met complexe typen

Complexe typen (MATRIX, MAP, STRUCT) worden standaard geretourneerd als JSON-tekenreeksen:

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

Troubleshooting

Deze sectie bevat richtlijnen voor het oplossen van veelvoorkomende problemen die kunnen optreden bij het gebruik van het Microsoft ADO.NET-stuurprogramma voor Microsoft Fabric Data Engineering.

Veelvoorkomende problemen

In de volgende secties worden veelvoorkomende problemen en hun oplossingen beschreven:

Verbindingsfouten

Probleem: Kan geen verbinding maken met Microsoft Fabric

Oplossingen:

1. Controleer FabricWorkspaceID en FabricLakehouseID zijn juiste GUID's
2. Azure CLI-verificatie controleren: az account show
3. Zorg ervoor dat u over de juiste Fabric werkruimtemachtigingen beschikt
4. Controleer de netwerkverbinding met api.fabric.microsoft.com

Authenticatiefouten

Probleem: verificatie mislukt met Azure CLI

Oplossingen:

• Voer az login uit om referentiegegevens te vernieuwen
• Controleer de juiste tenant: az account set --subscription <subscription-id>
• Controleer de geldigheid van het token: az account get-access-token --resource https://api.fabric.microsoft.com

Querytime-outs

Probleem: Time-outs van query's in grote datasets

Oplossingen:

• Time-out van query verhogen: LivyStatementTimeoutSeconds=300
• Gebruik LIMIT clausule om de resultaatgrootte tijdens de ontwikkeling te beperken
• Zorg ervoor dat het Spark-cluster voldoende resources heeft

Time-out voor het maken van sessies

Probleem: Er treedt een time-out op voor de verbinding tijdens het maken van een sessie

Oplossingen:

• Time-out van sessie verhogen: LivySessionTimeoutSeconds=120
• Beschikbaarheid van Fabric capaciteit controleren
• Controleren of de werkruimte geen sessielimieten heeft bereikt

Logboekregistratie inschakelen

Bij het oplossen van problemen kan het inschakelen van gedetailleerde logboekregistratie u helpen bij het identificeren van de hoofdoorzaak van problemen. U kunt logboekregistratie via de verbindingsreeks of programmatisch inschakelen.

Gedetailleerde logboekregistratie inschakelen via verbindingsreeks:

LogLevel=Debug

Ofwel programmeer een configuratie:

using Microsoft.Extensions.Logging;

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

// Logging is automatically integrated with the connection

Logboekniveaus:

• Trace: De meeste uitgebreide, omvat alle API-aanroepen
• Debug: Gedetailleerde informatie over foutopsporing
• Information: Algemene informatie (standaard)
• Warning: alleen waarschuwingen
• Error: alleen fouten

Verwante inhoud

• Apache Spark Runtimes in Fabric
• Fabric Runtime 1.3
• Wat is de Livy-API voor Data Engineering?
• Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering
• Microsoft ODBC-stuurprogramma voor Microsoft Fabric Data Engineering