Microsoft ADO.NET driver for Microsoft Fabric Data Engineering (forhåndsvisning)

Viktig!

ADO.NET er en mye brukt datatilgang i .NET-økosystemet som gjør det mulig for applikasjoner å koble til og arbeide med data fra databaser og store dataplattformer.

Microsoft ADO.NET Driver for Fabric Data Engineering lar deg koble til, spørre og administrere Spark-arbeidsbelastninger i Microsoft Fabric med påliteligheten og enkelheten til standard ADO.NET-mønstre. Bygget på Microsoft Fabrics Livy-API-er, gir driveren sikker og fleksibel Spark SQL-tilkobling til dine .NET-applikasjoner ved hjelp av kjente DbConnection, DbCommand, og DbDataReader abstraksjoner.

Viktige funksjoner

ADO.NET Compliant: Full implementering av ADO.NET abstraksjoner (DbConnection, DbCommand, DbDataReader, DbParameter, ) DbProviderFactory
Microsoft Entra ID-autentisering: Flere autentiseringsstrømmer, inkludert Azure CLI, interaktiv nettleser, klientopplysninger, sertifikatbasert autentisering og tilgangstokenautentisering
Spark SQL Native spørringsstøtte: Direkte kjøring av Spark SQL-setninger med parameteriserte spørringer
Omfattende støtte for datatyper: Støtte for alle Spark SQL-datatyper, inkludert komplekse typer (ARRAY, MAP, STRUCT)
Tilkoblingspooling: Innebygd tilkoblingspooladministrasjon for bedre ytelse
Gjenbruk av sesjoner: Effektiv Spark-sesjonshåndtering for å redusere oppstartsforsinkelse
Async Prefetch: Bakgrunnsdatainnlasting for bedre ytelse med store resultatsett
Auto-reconnect: Automatisk sesjonsgjenoppretting etter tilkoblingsfeil

Bemerkning

I åpen kildekode Apache Spark brukes database og skjema synonymt. For eksempel, å kjøre SHOW SCHEMAS eller SHOW DATABASES bruke en Fabric Notebook gir samme resultat — en liste over alle skjemaer i Lakehouse.

Forutsetninger

Før du bruker Microsoft ADO.NET Driver for Microsoft Fabric Data Engineering, må du sørge for at du har:

.NET-kjøretid: .NET 8.0 eller nyere
Microsoft Fabric Access: Tilgang til et Microsoft Fabric-arbeidsområde med Data Engineering-funksjonalitet
Azure Entra ID Credentials: Passende legitimasjon for autentisering
Workspace- og Lakehouse-ID-er: GUID-identifikatorer for ditt Fabric workspace og lakehouse
Azure CLI (optional): Required for Azure CLI authentication method

Last ned, inkludere, referer til og verifiser

Last ned NuGet-pakken

Microsoft ADO.NET Driver for Microsoft Fabric Data Engineering versjon 1.0.0 er i offentlig forhåndsvisning, som du kan laste ned fra disse nedlastingslenkene.

Referanse NuGet-pakken i prosjektet ditt

Inkluder den nedlastede NuGet-pakken i prosjektet ditt og legg til en referanse for pakken i prosjektfilen din:

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

Bekreft installasjon

Etter inkludering og referanse, sjekk at pakken er tilgjengelig i prosjektet ditt:

using Microsoft.Spark.Livy.AdoNet;

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

Eksempel på hurtigstart

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

Tilkoblingsstrengformat

Grunnleggende format

Microsoft ADO.NET Driver bruker standard ADO.NET tilkoblingsstrengformat:

Parameter1=Value1;Parameter2=Value2;...

Påkrevde parametere

Parameter	Beskrivelse	Eksempel
`Server`	Microsoft Fabric API-endepunkt	`https://api.fabric.microsoft.com/v1`
`SparkServerType`	Servertypeidentifikator	`Fabric`
`FabricWorkspaceID`	Microsoft Fabric arbeidsområdeidentifikator (GUID)	`<workspace-id>`
`FabricLakehouseID`	Microsoft Fabric lakehouse-identifikator (GUID)	`<lakehouse-id>`
`AuthFlow`	Godkjenningsmetode	`AzureCli`, `BrowserBased`, , `ClientSecretCredentialClientCertificateCredential`, `AuthAccessToken`, ,`FileToken`

Valgfrie parametere

Tilkoblingsinnstillinger

Parameter	Type	Forhåndsinnstilt	Beskrivelse
`LivySessionTimeoutSeconds`	Integer	`60`	Tid i sekunder for å vente på økt opprettelse
`LivyStatementTimeoutSeconds`	Integer	`600`	Tid i sekunder for å vente på setningsutførelse
`SessionName`	String	(auto)	Egendefinert navn for Spark-økten
`AutoReconnect`	boolsk	`false`	Aktiver automatisk sesjonsgjenoppretting

Innstillinger for tilkoblingspool

Parameter	Type	Forhåndsinnstilt	Beskrivelse
`ConnectionPoolEnabled`	boolsk	`true`	Aktiver tilkoblingspooling
`MinPoolSize`	Integer	`1`	Minimum tilkoblinger i bassenget
`MaxPoolSize`	Integer	`20`	Maksimale forbindelser i bassenget
`ConnectionMaxIdleTimeMs`	Integer	`1800000`	Maksimal tomgangstid før tilkobling resirkuleres (30 min)
`MaxLifetimeMs`	Integer	`3600000`	Maksimal levetid for en poolet tilkobling (60 min)
`ValidateConnections`	boolsk	`true`	Valider tilkoblinger før bruk
`ValidationTimeoutMs`	Integer	`5000`	Timeout for tilkoblingsvalidering

Loggingsinnstillinger

Parameter	Type	Forhåndsinnstilt	Beskrivelse
`LogLevel`	String	`Information`	Log-nivå: `Trace`, `Debug`, `Information`, , `Warning`, `Error`
`LogFilePath`	String	(ingen)	Sti for filbasert logging

Bemerkning

Kryssdriver-aliaser: Føreren godtar JDBC- og ODBC-egenskapsnavn i tillegg til native ADO.NET navn (f.eks. WorkspaceId mapps to FabricWorkspaceID, LakehouseId maps to FabricLakehouseID). Alle eiendomsnavn er små og små bokstaver.

Eksempler på tilkoblingsstrenger

Basic connection (Azure CLI authentication)

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

Med tilkoblingspooling-alternativer

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 gjenoppkobling og logging

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

Autentisering

Microsoft ADO.NET Driver støtter flere autentiseringsmetoder via Microsoft Entra ID (tidligere Azure Active Directory). Autentisering konfigureres ved å bruke parameteren AuthFlow i tilkoblingsstrengen.

Godkjenningsmetoder

AuthFlow-verdi	Beskrivelse	Best For
`AzureCli`	Uses Azure CLI cached credentials	Utvikling og testing
`BrowserBased`	Interaktiv nettleserbasert autentisering	Brukerrettede applikasjoner
`ClientSecretCredential`	Tjenesteprinsipp med klienthemmelighet	Automatiserte tjenester, bakgrunnsjobber
`ClientCertificateCredential`	Tjenesteansvarlig med sertifikat	Enterprise-programmer
`AuthAccessToken`	Forhåndsanskaffet bærertilgangstoken	Tilpassede autentiseringsscenarier

Azure CLI-autentisering

Best for: Utvikling og testing

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

Forutsetninger:

Azure CLI installed: az --version
Innlogget: az login

Interaktiv nettleserautentisering

Best for: Brukerrettede applikasjoner

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

Virkemåte:

Åpner et nettleservindu for brukerautentisering
Legitimasjon caches for påfølgende tilkoblinger

Autentisering av klientlegitimasjon (tjenesteprincipal)

Best for: Automatiserte tjenester og bakgrunnsjobber

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

Nødvendige parametere:

AuthTenantID: Azure tenant ID
AuthClientID: Applikasjons-(klient-)ID fra Microsoft Entra-ID
AuthClientSecret: Klienthemmelighet fra Microsoft Entra-ID

Sertifikatbasert godkjenning

Best for: Bedriftsapplikasjoner som krever sertifikatbasert 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();

Nødvendige parametere:

AuthTenantID: Azure tenant ID
AuthClientID: Applikasjons-ID (klient-ID)
AuthCertificatePath: Vei til PFX/PKCS12-sertifikatfilen
AuthCertificatePassword: Sertifikatpassord

Autentisering av tilgangstoken

Best for: Tilpassede autentiseringsscenarier

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

Bemerkning

Vi anbefaler sterkt å unngå hardkoding av legitimasjoner som passord, nøkler, hemmeligheter, tokens eller sertifikater i koden din. Bruk i stedet Azure Key Vault for å lagre disse verdiene sikkert og hente dem under kjøring.

Brukseksempler

Grunnleggende tilkobling og spørring

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

Parameteriserte spørringer

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 for enkeltverdier

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

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

ExecuteNonQuery for DML-operasjoner

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

Arbeid med store resultatsett

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

Skjemaoppdagelse

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

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

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

Tilordning av datatype

Driveren mapper Spark SQL-datatyper til .NET-typer:

Spark SQL Type	.NET-type	DbType
BOOLSK	`bool`	boolsk
TINYINT	`sbyte`	SByte
SMALLINT	`short`	Int16
INT	`int`	Int32
BIGINT	`long`	Int64
FLYTE	`float`	Enkel
DOBBEL	`double`	Dobbel
DECIMAL(p,s)	`decimal`	Desimal
STRENG	`string`	String
VARCHAR(n)	`string`	String
CHAR(n)	`string`	String
BINÆR	`byte[]`	Binary
DATO	`DateTime`	Dato
TIDSSTEMPEL	`DateTime`	Date/klokkeslett
ARRAY<T>	`T[]` eller `string` (JSON)	Objekt
KART<K,V>	`Dictionary<K,V>` eller `string` (JSON)	Objekt
STRUCT	`object` eller `string` (JSON)	Objekt

Arbeid med komplekse typer

Komplekse typer (ARRAY, MAP, STRUCT) returneres som JSON-strenger 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);
}

Feilsøking

Denne delen gir veiledning for å løse vanlige problemer du kan støte på når du bruker Microsoft ADO.NET Driver for Microsoft Fabric Data Engineering.

Vanlige problemer

Følgende avsnitt beskriver vanlige problemer og deres løsninger:

Tilkoblingsfeil

Problem: Kan ikke koble til Microsoft Fabric

Løsninger:

Verifiser FabricWorkspaceID og FabricLakehouseID er korrekte GUID-er
Check Azure CLI authentication: az account show
Sørg for at du har riktige Fabric-arbeidsområdetillatelser
Sjekk nettverkstilkoblingen til api.fabric.microsoft.com

Godkjenningsfeil

Problem: Autentisering feiler med Azure CLI

Løsninger:

Kjør az login for å oppdatere legitimasjonen
Sjekk riktig leietaker: az account set --subscription <subscription-id>
Sjekk tokenets gyldighet: az account get-access-token --resource https://api.fabric.microsoft.com

Spørringstidsavbrudd

Problem: Forespørsler går ut på store tabeller

Løsninger:

Øk tidsbegrensningen på kontoutskriften: LivyStatementTimeoutSeconds=300
Bruk LIMIT klausulen for å begrense resultatstørrelsen under utvikling
Sørg for at Spark-klyngen har tilstrekkelige ressurser

Timeout for oppretting av økter

Problem: Tilkoblingen går ut på tid under opprettelsen av en økt

Løsninger:

Øk timeouten i øktene: LivySessionTimeoutSeconds=120
Sjekk tilgjengelighet av Fabric-kapasitet
Sjekk at arbeidsområdet ikke har nådd sesjonsgrenser

Aktiver logging

Når du feilsøker problemer, kan det å aktivere detaljert logging hjelpe deg med å identifisere rotårsaken til problemene. Du kan aktivere logging via tilkoblingsstrengen eller programmatisk.

For å muliggjøre detaljert logging via tilkoblingsstreng:

LogLevel=Debug

Eller konfigurere programmatisk:

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 omfangsfull, inkluderer alle API-kall
Debug: Detaljert feilsøkingsinformasjon
Information: Generell informasjon (standard)
Warning: Kun advarsler
Error: Kun feil

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2026-03-18

Microsoft ADO.NET driver for Microsoft Fabric Data Engineering (forhåndsvisning)

Viktige funksjoner

Forutsetninger

Last ned, inkludere, referer til og verifiser

Last ned NuGet-pakken

Referanse NuGet-pakken i prosjektet ditt

Bekreft installasjon

Eksempel på hurtigstart

Tilkoblingsstrengformat

Grunnleggende format

Påkrevde parametere

Valgfrie parametere

Tilkoblingsinnstillinger

Innstillinger for tilkoblingspool

Loggingsinnstillinger

Eksempler på tilkoblingsstrenger

Basic connection (Azure CLI authentication)

Med tilkoblingspooling-alternativer

Med automatisk gjenoppkobling og logging

Autentisering

Godkjenningsmetoder

Azure CLI-autentisering

Interaktiv nettleserautentisering

Autentisering av klientlegitimasjon (tjenesteprincipal)

Sertifikatbasert godkjenning

Autentisering av tilgangstoken

Brukseksempler

Grunnleggende tilkobling og spørring

Parameteriserte spørringer

ExecuteScalar for enkeltverdier

ExecuteNonQuery for DML-operasjoner

Arbeid med store resultatsett

Skjemaoppdagelse

Bruk av LivyConnectionStringBuilder

Bruk av DbProviderFactory

Tilordning av datatype

Arbeid med komplekse typer

Feilsøking

Vanlige problemer

Tilkoblingsfeil

Godkjenningsfeil

Spørringstidsavbrudd

Timeout for oppretting av økter

Aktiver logging

Relatert innhold

Tilbakemeldinger

Flere ressurser