โปรแกรมควบคุม Microsoft ADO.NET สําหรับ Microsoft Fabric Data Engineering (พรีวิว)

ADO.NET เป็นเทคโนโลยีการเข้าถึงข้อมูลที่นํามาใช้อย่างแพร่หลายในระบบนิเวศ .NET ที่ช่วยให้แอปพลิเคชันสามารถเชื่อมต่อและทํางานกับข้อมูลจากฐานข้อมูลและแพลตฟอร์มข้อมูลขนาดใหญ่ได้

ไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering ช่วยให้คุณเชื่อมต่อ สืบค้น และจัดการงาน Spark ใน Fabric ด้วยความน่าเชื่อถือและความเรียบง่ายของรูปแบบมาตรฐาน ADO.NET ไดรเวอร์นี้สร้างขึ้นบน Fabric Livy APIs เพื่อให้การเชื่อมต่อ Spark SQL ที่ปลอดภัยและยืดหยุ่นกับแอปพลิเคชัน .NET ของคุณโดยใช้ , DbConnection, และDbCommandนามธรรมที่คุ้นเคยDbDataReader

คุณลักษณะสำคัญ

• สอดคล้องกับ ADO.NET: การใช้งานนามธรรม ADO.NET อย่างเต็มรูปแบบ (DbConnection, , DbCommand, DbDataReader, DbParameter) DbProviderFactory
• การรับรองความถูกต้องของ Microsoft Entra ID: โฟลว์การรับรองความถูกต้องหลายรายการ รวมถึง Azure CLI, เบราว์เซอร์แบบโต้ตอบ, ข้อมูลประจําตัวไคลเอ็นต์, ตามใบรับรอง และการรับรองความถูกต้องของโทเค็นการเข้าถึง
• รองรับการสืบค้นแบบเนทีฟของ Spark SQL: การดําเนินการโดยตรงของคําสั่ง Spark SQL ด้วยแบบสอบถามที่มีพารามิเตอร์
• รองรับประเภทข้อมูลที่ครอบคลุม: รองรับประเภทข้อมูล Spark SQL ทั้งหมดรวมถึงประเภทที่ซับซ้อน (ARRAY, MAP, STRUCT)
• Connection Pooling: การจัดการพูลการเชื่อมต่อในตัวเพื่อประสิทธิภาพที่ดีขึ้น
• การนําเซสชันกลับมาใช้ใหม่: การจัดการเซสชัน Spark ที่มีประสิทธิภาพเพื่อลดเวลาแฝงในการเริ่มต้น
• Async Prefetch: การโหลดข้อมูลพื้นหลังเพื่อประสิทธิภาพที่ดีขึ้นด้วยชุดผลลัพธ์ขนาดใหญ่
• เชื่อมต่อใหม่อัตโนมัติ: การกู้คืนเซสชันอัตโนมัติหลังจากการเชื่อมต่อล้มเหลว

ข้อกำหนดเบื้องต้น

ก่อนใช้ไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering โปรดตรวจสอบให้แน่ใจว่าคุณมี:

• รันไทม์ .NET: .NET 8.0 หรือใหม่กว่า
• Fabric Access: การเข้าถึงพื้นที่ทํางาน Fabric ด้วยความสามารถด้านวิศวกรรมข้อมูล
• ข้อมูลประจําตัว Azure Entra ID: ข้อมูลประจําตัวที่เหมาะสมสําหรับการรับรองความถูกต้อง
• รหัสพื้นที่ทํางานและเลคเฮาส์: ตัวระบุ GUID สําหรับพื้นที่ทํางาน Fabric และเลคเฮาส์ของคุณ
• Azure CLI (ไม่บังคับ): จําเป็นสําหรับวิธีการรับรองความถูกต้องของ Azure CLI

ดาวน์โหลด รวม อ้างอิง และตรวจสอบ

ดาวน์โหลดแพ็คเกจ NuGet

ไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering เวอร์ชัน 1.0.0 อยู่ในโหมดพรีวิวสาธารณะ ซึ่งคุณสามารถดาวน์โหลดได้จากลิงก์ศูนย์ดาวน์โหลดเหล่านี้

• ดาวน์โหลดไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering (zip)
• ดาวน์โหลดไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering (tar)

อ้างอิงแพ็คเกจ NuGet ในโครงการของคุณ

รวมแพ็คเกจ NuGet ที่ดาวน์โหลดมาในโครงการของคุณและเพิ่มการอ้างอิงของแพ็คเกจไปยังไฟล์โครงการของคุณ:

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

ตรวจสอบการติดตั้ง

หลังจากรวมและอ้างอิงแล้ว ให้ตรวจสอบว่าแพ็คเกจพร้อมใช้งานในโครงการของคุณ:

using Microsoft.Spark.Livy.AdoNet;

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

ตัวอย่างการเริ่มต้นอย่างรวดเร็ว

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

รูปแบบสตริงการเชื่อมต่อ

รูปแบบพื้นฐาน

โปรแกรมควบคุม Microsoft ADO.NET ใช้รูปแบบสตริงการเชื่อมต่อ ADO.NET มาตรฐาน:

Parameter1=Value1;Parameter2=Value2;...

พารามิเตอร์ที่ต้องการ

พารามิเตอร์เพิ่มเติม

การตั้งค่าการเชื่อมต่อ

การตั้งค่าพูลการเชื่อมต่อ

การตั้งค่าการบันทึก

ตัวอย่างสตริงการเชื่อมต่อ

การเชื่อมต่อพื้นฐาน (การรับรองความถูกต้อง Azure CLI)

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

ด้วยตัวเลือกการรวมการเชื่อมต่อ

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

ด้วยการเชื่อมต่อใหม่และการบันทึกอัตโนมัติ

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

การพิสูจน์ตัวตน

โปรแกรมควบคุม Microsoft ADO.NET สนับสนุนวิธีการรับรองความถูกต้องหลายวิธีผ่าน Microsoft Entra ID (เดิมคือ Azure Active Directory) การรับรองความถูกต้องถูกกําหนดค่าโดยใช้ AuthFlow พารามิเตอร์ในสตริงการเชื่อมต่อ

วิธีการรับรองความถูกต้อง

การรับรองความถูกต้องของ Azure CLI

ดีที่สุดสําหรับ: การพัฒนาและการทดสอบ

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

ข้อกําหนดเบื้องต้น:

• ติดตั้ง Azure CLI: az --version
• เข้าสู่ระบบ: az login

การรับรองความถูกต้องของเบราว์เซอร์แบบโต้ตอบ

ดีที่สุดสําหรับ: แอปพลิเคชันที่ต้องเผชิญหน้ากับผู้ใช้

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

ลักษณะการทํางาน:

• เปิดหน้าต่างเบราว์เซอร์สําหรับการตรวจสอบผู้ใช้
• ข้อมูลประจําตัวจะถูกแคชสําหรับการเชื่อมต่อที่ตามมา

การรับรองความถูกต้องของข้อมูลประจําตัวไคลเอ็นต์ (บริการหลัก)

ดีที่สุดสําหรับ: บริการอัตโนมัติและงานเบื้องหลัง

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

พารามิเตอร์ที่จําเป็น:

• AuthTenantID: รหัสผู้เช่า Azure
• AuthClientID: รหัสแอปพลิเคชัน (ไคลเอ็นต์) จาก Microsoft Entra ID
• AuthClientSecret: ข้อมูลลับของไคลเอ็นต์จาก Microsoft Entra ID

การรับรองความถูกต้องตามใบรับรอง

ดีที่สุดสําหรับ: แอปพลิเคชันระดับองค์กรที่ต้องการการรับรองความถูกต้องตามใบรับรอง

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

พารามิเตอร์ที่จําเป็น:

• AuthTenantID: รหัสผู้เช่า Azure
• AuthClientID: รหัสแอปพลิเคชัน (ไคลเอ็นต์)
• AuthCertificatePath: เส้นทางไปยังไฟล์ใบรับรอง PFX/PKCS12
• AuthCertificatePassword: รหัสผ่านใบรับรอง

การรับรองความถูกต้องของโทเค็นการเข้าถึง

ดีที่สุดสําหรับ: สถานการณ์การรับรองความถูกต้องแบบกําหนดเอง

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

ตัวอย่างการใช้

การเชื่อมต่อและแบบสอบถามพื้นฐาน

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

คิวรีแบบกําหนดพารามิเตอร์

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 สําหรับค่าเดียว

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

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

ExecuteNonQuery สําหรับการดําเนินการ 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($"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)");

การทํางานกับชุดผลลัพธ์ขนาดใหญ่

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

การค้นพบสคีมา

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

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

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

การแมปชนิดข้อมูล

ไดรเวอร์แมปชนิดข้อมูล Spark SQL กับชนิด .NET:

การทํางานกับประเภทที่ซับซ้อน

ประเภทที่ซับซ้อน (ARRAY, MAP, STRUCT) จะถูกส่งคืนเป็นสตริง JSON ตามค่าเริ่มต้น:

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

แก้ไข ปัญหา

ส่วนนี้ให้คําแนะนําในการแก้ไขปัญหาทั่วไปที่คุณอาจพบเมื่อใช้งานไดรเวอร์ Microsoft ADO.NET สําหรับ Fabric Data Engineering

ปัญหาทั่วไป

ส่วนต่อไปนี้จะอธิบายปัญหาทั่วไปและวิธีแก้ไข:

การเชื่อมต่อล้มเหลว

ปัญหา: ไม่สามารถเชื่อมต่อกับ Fabric ได้

โซลูชัน:

1. ตรวจสอบ FabricWorkspaceID และเป็น FabricLakehouseID GUID ที่ถูกต้อง
2. ตรวจสอบการรับรองความถูกต้อง Azure CLI: az account show
3. ตรวจสอบให้แน่ใจว่าคุณมีสิทธิ์พื้นที่ทํางาน Fabric ที่เหมาะสม
4. ตรวจสอบการเชื่อมต่อเครือข่ายเพื่อ api.fabric.microsoft.com

ข้อผิดพลาดในการรับรองความถูกต้อง

ปัญหา: การรับรองความถูกต้องล้มเหลวด้วย Azure CLI

โซลูชัน:

• เรียกใช้ az login เพื่อรีเฟรชข้อมูลประจําตัว
• ตรวจสอบผู้เช่าที่ถูกต้อง: az account set --subscription <subscription-id>
• ตรวจสอบความถูกต้องของโทเค็น: az account get-access-token --resource https://api.fabric.microsoft.com

หมดเวลาคิวรี

ปัญหา: การสืบค้นหมดเวลาบนตารางขนาดใหญ่

โซลูชัน:

• เพิ่มการหมดเวลาของใบแจ้งยอด: LivyStatementTimeoutSeconds=300
• ใช้ LIMIT ส่วนคําสั่งเพื่อจํากัดขนาดผลลัพธ์ระหว่างการพัฒนา
• ตรวจสอบให้แน่ใจว่าคลัสเตอร์ Spark มีทรัพยากรเพียงพอ

หมดเวลาการสร้างเซสชัน

ปัญหา: การเชื่อมต่อหมดเวลาระหว่างการสร้างเซสชัน

โซลูชัน:

• เพิ่มการหมดเวลาของเซสชัน: LivySessionTimeoutSeconds=120
• ตรวจสอบความพร้อมใช้งานของความจุ Fabric
• ตรวจสอบว่าพื้นที่ทํางานยังไม่ถึงขีดจํากัดเซสชัน

เปิดใช้งานการบันทึก

เมื่อแก้ไขปัญหา การเปิดใช้งานการบันทึกโดยละเอียดสามารถช่วยคุณระบุสาเหตุของปัญหาได้ คุณสามารถเปิดใช้งานการบันทึกผ่านสตริงการเชื่อมต่อหรือโดยทางโปรแกรม

วิธีเปิดใช้งานการบันทึกโดยละเอียดผ่านสตริงการเชื่อมต่อ:

LogLevel=Debug

หรือกําหนดค่าโดยทางโปรแกรม:

using Microsoft.Extensions.Logging;

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

// Logging is automatically integrated with the connection

ระดับบันทึก:

• Trace: ฟุ่มเฟือยที่สุด รวมถึงการเรียก API ทั้งหมด
• Debug: ข้อมูลการดีบักโดยละเอียด
• Information: ข้อมูลทั่วไป (ค่าเริ่มต้น)
• Warning: คําเตือนเท่านั้น
• Error: ข้อผิดพลาดเท่านั้น

เนื้อหาที่เกี่ยวข้อง

• รันไทม์ Apache Spark ใน Fabric
• รันไทม์ของผ้า 1.3
• Livy API สําหรับวิศวกรรมข้อมูลคืออะไร
• ไดรเวอร์ Microsoft JDBC สําหรับ Fabric Data Engineering
• ไดรเวอร์ Microsoft ODBC สําหรับ Fabric Data Engineering