Microsoft ADO.NET -ajuri Microsoft Fabric Data Engineeringille (esikatselu)

ADO.NET on laajasti käytössä oleva datan käyttöteknologia .NET-ekosysteemissä, joka mahdollistaa sovellusten yhteyden tietokantojen ja big data -alustojen datan kanssa työskentelyyn.

Microsoft ADO.NET Driver for Fabric Data Engineering mahdollistaa Spark-työkuormien yhdistämisen, kyselyn ja hallinnan Microsoft Fabricissa tavallisten ADO.NET-mallien luotettavuudella ja yksinkertaisuudella. Microsoft Fabricin Livy-rajapintojen pohjalta rakennettu ajuri tarjoaa turvallisen ja joustavan Spark SQL -yhteyden .NET-sovelluksiin tuttujen DbConnection, DbCommand, ja DbDataReader abstraktioiden avulla.

Tärkeimmät ominaisuudet

• ADO.NET Yhteensopivuus: ADO.NET abstraktioidenDbConnection (, DbCommand, DbDataReaderDbParameter, DbProviderFactory, ) täysi toteutus
• Microsoft Entra ID -tunnistautuminen: Useita todennusprosesseja, mukaan lukien Azure CLI, interaktiivinen selain, asiakastunnukset, varmennepohjainen ja pääsytunnusen tunnistautuminen
• Spark SQL Native Query Support: Spark SQL -lauseiden suora suoritus parametrisoiduilla kyselyillä
• Kattava tietotyyppituki: Tuki kaikille Spark SQL -tietotyypeille, mukaan lukien monimutkaiset tyypit (TAULUKKO, KARTTA, RAKENNE)
• Connection pooling: Sisäänrakennettu yhteyspoolin hallinta suorituskyvyn parantamiseksi
• Session uudelleenkäyttö: Tehokas Spark-istuntojen hallinta käynnistysviiveen vähentämiseksi
• Asynkroninen esilataus: Taustalla lataava datan lataus parantaa suorituskykyä suurilla tulosjoukoilla
• Automaattinen uudelleenyhdistäminen: Automaattinen istunnon palautus yhteyden epäonnistumisen jälkeen

Edellytykset

Ennen Microsoft ADO.NET Driverin käyttöä Microsoft Fabric Data Engineeringille varmista, että sinulla on:

• .NET Runtime: .NET 8.0 tai uudempi
• Microsoft Fabric Access: Pääsy Microsoft Fabricin työtilaan, jossa on data-insinöörin ominaisuudet
• Azure Entra ID Credentials: Sopivat tunnistetiedot autentikointiin
• Workspace- ja Lakehouse-tunnisteet: GUID-tunnisteet Fabric-työtilallesi ja järvenrakennukselle
• Azure CLI (valinnainen): Vaaditaan Azure CLI -todennusmenetelmälle

Lataa, sisällytä, viittaa ja varmista

Lataa NuGet-paketti

Microsoft ADO.NET Driver for Microsoft Fabric Data Engineering versio 1.0.0 on julkisessa esikatselussa, jonka voit ladata näistä latauskeskuksen linkeistä.

• Lataa Microsoft ADO.NET Driver for Microsoft Fabric Data Engineering (zip)
• Lataa Microsoft ADO.NET Driver for Microsoft Fabric Data Engineering (tar)

Viittaa NuGet-pakettiin projektissasi

Sisällytä ladattu NuGet-paketti projektiisi ja lisää paketin viite projektitiedostoosi:

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

Asennuksen tarkistaminen

Sisällytyksen ja viitteen jälkeen varmista, että paketti on saatavilla projektissasi:

using Microsoft.Spark.Livy.AdoNet;

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

Nopea aloitusesimerkki

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

Yhteysmerkkijonomuoto

Perusformaatti

Microsoft ADO.NET Driver käyttää tavallista ADO.NET-yhteysmerkkijonomuotoa:

Parameter1=Value1;Parameter2=Value2;...

Pakolliset parametrit

Valinnaiset parametrit

Yhteysasetukset

Yhteysaltaan asetukset

Lokiasetukset

Esimerkkejä yhteysmerkkijonoista

Perusyhteys (Azure CLI authentication)

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

Yhteyspoolausvaihtoehdoilla

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

Automaattisella uudelleenyhdistämisellä ja lokituksella

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

Todentaminen

Microsoft ADO.NET Driver tukee useita todennusmenetelmiä Microsoft Entra ID:n (entinen Azure Active Directory) kautta. Tunnistautuminen konfiguroidaan yhteysmerkkijonon AuthFlow parametrin avulla.

Todennusmenetelmät

Azure CLI authentication

Paras: Kehitykseen ja testaukseen

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

Edellytykset:

• Azure CLI asennettu: az --version
• Kirjautunut sisään: az login

Interaktiivinen selaimen tunnistautuminen

Parhaiten: Käyttäjäkohtaisille sovelluksille

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

Toiminta:

• Avaa selaimen ikkunan käyttäjän tunnistautumista varten
• Tunnistetiedot tallennetaan välimuistiin seuraavia yhteyksiä varten

Asiakastunnisteiden (palvelupäähenkilön) todennus

Paras: Automatisoidut palvelut ja taustatyöt

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

Vaaditut parametrit:

• AuthTenantID: Azure tenant ID
• AuthClientID: Application (client) ID Microsoft Entra ID:stä
• AuthClientSecret: Asiakassalaisuus Microsoft Entra ID:stä

Varmennepohjainen todentaminen

Paras: Yrityssovelluksiin, jotka vaativat varmennepohjaista todennusta

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

Vaaditut parametrit:

• AuthTenantID: Azure tenant ID
• AuthClientID: Sovelluksen (asiakas) tunnus
• AuthCertificatePath: Polku PFX/PKCS12-varmennetiedostoon
• AuthCertificatePassword: Varmenteen salasana

Pääsytunnuksen tunnistautuminen

Parhaiten: Mukautetut todennusskenaariot

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

Käyttöesimerkkejä

Perusyhteys ja kysely

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

Parametrisoidut kyselyt

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 yksittäisille arvoille

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

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

ExecuteNonQuery DML-operaatioille

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

Työskentely suurten tulosjoukkojen kanssa

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

Skeeman löytö

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

LivyConnectionStringBuilderin käyttö

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

DbProviderFactoryn käyttö

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

Tietotyyppien kartoittaminen

Ajuri kartoittaa Spark SQL -tietotyypit .NET-tyyppeihin:

Työskentely monimutkaisten tyyppien kanssa

Kompleksityypit (ARRAY, MAP, STRUCT) palautetaan oletuksena JSON-merkkijonoina:

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

Vianmääritys

Tämä osio antaa ohjeita yleisten ongelmien ratkaisemiseen, joita saatat kohdata Microsoft ADO.NET Driver for Microsoft Fabric Data Engineering -ajuria käyttäessäsi.

Yleisiä ongelmia

Seuraavissa osioissa kuvataan yleisiä ongelmia ja niiden ratkaisuja:

Yhteyden epäonnistumiset

Ongelma: En saa yhteyttä Microsoft Fabriciin

Ratkaisut:

1. Varmista FabricWorkspaceID ja FabricLakehouseID ovatko oikeat GUID-tiedostot
2. Tarkista Azure CLI -autentikointi: az account show
3. Varmista, että sinulla on asianmukaiset Fabric-työtilaoikeudet
4. Varmista verkkoyhteys api.fabric.microsoft.com

Todennusvirheet

Ongelma: Todennus epäonnistuu Azure CLI:llä

Ratkaisut:

• Juokse az login päivittääksesi tunnukset
• Varmista oikea vuokralainen: az account set --subscription <subscription-id>
• Tarkista tokenin pätevyys: az account get-access-token --resource https://api.fabric.microsoft.com

Kyselyn aikakatkaisut

Ongelma: Kyselyt aikakatkaistuvat suurilla tauluilla

Ratkaisut:

• Lisää laskun aikakatkaisu: LivyStatementTimeoutSeconds=300
• Käytä LIMIT lauseketta rajoittamaan tuloskokoa kehityksen aikana
• Varmista, että Spark-klusterilla on riittävät resurssit

Session luomisen aikalisä

Ongelma: Yhteyden aikakatkaisu istunnon luomisen aikana

Ratkaisut:

• Pidennä istunnon aikakatkaisu: LivySessionTimeoutSeconds=120
• Tarkista kankaan kapasiteetin saatavuus
• Varmista, ettei työtila ole saavuttanut istuntorajoja

Lokituksen ottaminen käyttöön

Ongelmien vianetsinnässä yksityiskohtainen lokitus voi auttaa tunnistamaan juurisyyn. Voit ottaa lokituksen käyttöön yhteysjonon kautta tai ohjelmallisesti.

Yksityiskohtaisen lokituksen mahdollistamiseksi yhteysmerkkijonon kautta:

LogLevel=Debug

Tai konfiguroida ohjelmallisesti:

using Microsoft.Extensions.Logging;

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

// Logging is automatically integrated with the connection

Lokitasot:

• Trace: Monisanainen, sisältää kaikki API-kutsut
• Debug: Yksityiskohtaista virheenkorjaustietoa
• Information: Yleistä tietoa (oletus)
• Warning: Vain varoitukset
• Error: Vain virheet

Liittyvä sisältö

• Apache Spark -suoritusajat Fabricissa
• Kankaan käyttöaika 1.3
• Mikä on Livy API data-insinöörille
• Microsoft JDBC -ajuri Microsoft Fabric Data Engineeringille
• Microsoft ODBC -ajuri Microsoft Fabric Data Engineeringille