Controlador Microsoft ADO.NET para Microsoft Fabric Data Engineering

ADO.NET es una tecnología de acceso a datos ampliamente adoptada en el ecosistema de .NET que permite a las aplicaciones conectarse y trabajar con datos de bases de datos y plataformas de macrodatos.

El controlador Microsoft ADO.NET para Fabric Data Engineering te permite conectar, consultar y gestionar cargas de trabajo Spark en Fabric con la fiabilidad y simplicidad de los patrones estándar de ADO.NET. Basado en las API de Livy de Fabric, el controlador proporciona conectividad segura y flexible de Spark SQL para tus aplicaciones .NET mediante las conocidas abstracciones DbConnection, DbCommand y DbDataReader.

Características clave

• APIs ADO.NET: Familiares DbConnection, DbCommand, DbDataReader, DbParameter, y DbProviderFactory abstracciones para la conectividad SQL de Spark
• Autenticación de Microsoft Entra ID: varios flujos de autenticación, como la CLI de Azure, el explorador interactivo, las credenciales de cliente, la autenticación basada en certificados y el token de acceso
• Compatibilidad con consultas nativas de Spark SQL: ejecución directa de instrucciones SQL de Spark con consultas con parámetros
• Compatibilidad completa con tipos de datos: compatibilidad con todos los tipos de datos de Spark SQL, incluidos tipos complejos (ARRAY, MAP, STRUCT)
• Agrupación de conexiones: administración integrada de grupos de conexiones para mejorar el rendimiento
• Reutilización de sesión: administración eficaz de sesiones de Spark para reducir la latencia de inicio
• Sesiones de alta concurrencia: Opta por compartir la capacidad de Fabric Livy con REPLs separados para sesiones HC alquiladas simultáneamente
• Captura previa asincrónica: carga de datos en segundo plano para mejorar el rendimiento con grandes conjuntos de resultados
• Reconexión automática: Recuperación de la sesión clásica tras fallos de conexión; los fallos de HC se notifican para que la aplicación controle el reintento

Prerrequisitos

Antes de utilizar el controlador Microsoft ADO.NET para Fabric Data Engineering, asegúrate de que tienes:

• Runtime de .NET: .NET 8.0 o posterior
• Fabric Access: Acceso a un espacio de trabajo de Fabric con capacidades de Ingeniería de Datos
• Credenciales de id. de Azure Entra: credenciales adecuadas para la autenticación
• Identificadores de área de trabajo y Lakehouse: identificadores GUID para tu área de trabajo de Fabric y Lakehouse
• CLI de Azure (opcional): necesario para el método de autenticación de la CLI de Azure

Descarga, inclusión, referencia y comprobación

Descarga del paquete NuGet

• Descargar el controlador Microsoft ADO.NET para Fabric Data Engineering (zip)
• Descargar el controlador Microsoft ADO.NET para Fabric Data Engineering (tar)

Hacer referencia al paquete NuGet en el proyecto

Incluya el paquete NuGet descargado en el proyecto y agregue una referencia del paquete al archivo del proyecto:

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

Comprobación de la instalación

Después de incluir y hacer referencia, compruebe que el paquete está disponible en el proyecto:

using Microsoft.Spark.Livy.AdoNet;

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

Ejemplo de inicio rápido

using Microsoft.Spark.Livy.AdoNet;

// Connection string with required parameters
string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "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));
}

Formato de la cadena de conexión

Formato básico

Microsoft ADO.NET Driver usa el formato estándar de cadena de conexión ADO.NET:

Parameter1=Value1;Parameter2=Value2;...

Parámetros necesarios

Parámetros opcionales

Configuración de conexión

Configuración del grupo de conexiones

Configuraciones de alta concurrencia

Configuración de registro

Alias de controladores cruzados: El controlador acepta nombres de propiedad JDBC y ODBC además de nombres de ADO.NET nativos (por ejemplo, WorkspaceId se asigna a FabricWorkspaceID, LakehouseId se asigna a FabricLakehouseID). Todos los nombres de propiedad no distinguen mayúsculas de minúsculas.

Ejemplos de cadena de conexión

Conexión básica (autenticación de la CLI de Azure)

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

Conexión de alta concurrencia

La alta concurrencia está disponible para las conexiones de Microsoft Fabric. Establezca HcEnabled=true; las APIs estándar de conexión y comandos ADO.NET permanecen sin cambios. Utiliza el host no versionado de la API de Fabric para Server; el controlador usa FabricVersion=v1 y LivyApiVersion=2023-12-01 de forma predeterminada cuando construye el extremo de HC.

using Microsoft.Spark.Livy.AdoNet;

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AzureCli;" +
    "HcEnabled=true;";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

using var command = connection.CreateCommand();
command.CommandText = "SELECT 1 AS value";

object? result = await command.ExecuteScalarAsync();
Console.WriteLine($"Result: {result}");

Para obtener una guía completa sobre la configuración, consulte la sección Modo High-Concurrency (HC).

Con opciones de agrupación de conexiones

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

Con la reconexión automática y el registro

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

Autenticación

Microsoft ADO.NET Driver admite varios métodos de autenticación a través de Microsoft Entra ID (anteriormente Azure Active Directory). La autenticación se configura mediante el AuthFlow parámetro en la cadena de conexión.

Métodos de autenticación

Autenticación de la CLI de Azure

Mejor para: Desarrollo y pruebas

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

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Requisitos previos:

• CLI de Azure instalada: az --version
• Iniciado sesión: az login

Autenticación interactiva del explorador

Mejor para: aplicaciones orientadas al usuario

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

Comportamiento:

• Abre una ventana del explorador para la autenticación de usuario
• Las credenciales se almacenan en caché para las conexiones posteriores

Autenticación de credenciales de cliente (Principal de Servicio)

Mejor para: Servicios automatizados y trabajos en segundo plano

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

Parámetros necesarios:

• AuthTenantID: identificador de inquilino de Azure
• AuthClientID: ID de aplicación (cliente) de Microsoft Entra ID
• AuthClientSecret: secreto de cliente de Microsoft Entra ID

Autenticación basada en certificados

Mejor para: Aplicaciones empresariales que requieren autenticación basada en certificados

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

Parámetros necesarios:

• AuthTenantID: identificador de inquilino de Azure
• AuthClientID: ID de aplicación (cliente)
• AuthCertificatePath: ruta de acceso al archivo de certificado PFX/PKCS12
• AuthCertificatePassword: contraseña de certificado

Autenticación de token de acceso

Mejor para: Escenarios de autenticación personalizados

// Acquire token through your custom mechanism
string accessToken = await AcquireTokenFromCustomSourceAsync();

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "SparkServerType=Fabric;" +
    "FabricWorkspaceID=<workspace-id>;" +
    "FabricLakehouseID=<lakehouse-id>;" +
    "AuthFlow=AuthAccessToken;" +
    $"AuthAccessToken={accessToken};";

using var connection = new LivyConnection(connectionString);
await connection.OpenAsync();

Ejemplos de uso

Conexión básica y consulta

using Microsoft.Spark.Livy.AdoNet;

string connectionString =
    "Server=https://api.fabric.microsoft.com;" +
    "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();
}

Consultas parametrizadas

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 para valores únicos

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

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

ExecuteNonQuery para operaciones 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(rowsAffected >= 0
    ? $"Inserted {rowsAffected} row(s)"
    : "The insert completed, but the driver didn't return an update count.");

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

rowsAffected = await updateCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Updated {rowsAffected} row(s)"
    : "The update completed, but the driver didn't return an update count.");

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

rowsAffected = await deleteCommand.ExecuteNonQueryAsync();
Console.WriteLine(rowsAffected >= 0
    ? $"Deleted {rowsAffected} row(s)"
    : "The delete completed, but the driver didn't return an update count.");

Trabajar con grandes conjuntos de resultados

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

Detección de esquemas

// 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())
{
    int tableNameOrdinal = tablesReader.GetOrdinal("tableName");
    Console.WriteLine($"  {tablesReader.GetString(tableNameOrdinal)}");
}

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

// Show databases
using var dbCommand = connection.CreateCommand();
dbCommand.CommandText = "SHOW DATABASES";

using var dbReader = await dbCommand.ExecuteReaderAsync();
Console.WriteLine("\nAvailable databases:");
while (await dbReader.ReadAsync())
{
    Console.WriteLine($"  {dbReader.GetString(0)}");
}

Uso de LivyConnectionStringBuilder

using Microsoft.Spark.Livy.AdoNet;

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

using var connection = new LivyConnection(builder.ConnectionString);
await connection.OpenAsync();

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

Modo de alta concurrencia (HC)

El modo de alta concurrencia (HC) ayuda a las aplicaciones .NET a ejecutar cargas de trabajo SQL de Spark concurrentes sin necesidad de provisionar una sesión clásica separada de Spark para cada conexión ADO.NET. Fabric puede colocar conexiones compatibles en la misma sesión de Livy gestionada por el servidor y proporcionar a cada conexión un bucle aislado de lectura, evaluación e impresión (REPL) para la ejecución de instrucciones.

Este modelo puede reducir el tiempo de inicio de la conexión, evitar la provisión repetida de sesiones de Spark y utilizar la capacidad de Fabric Spark de forma más eficiente. Tu aplicación sigue utilizando APIs estándar de ADO.NET, incluyendo DbConnection, DbCommand, DbDataReader, OpenAsync, y Close.

El modo HC es opcional. Si no lo activas, el controlador usa la ruta de sesión clásica de Livy.

Elige entre HC y modo clásico

Usa el modo HC cuando:

• Un servicio ASP.NET gestiona solicitudes concurrentes que abren conexiones y ejecutan Spark SQL.
• Un servicio de trabajo, un trabajo programado o una canalización de datos en paralelo crea ráfagas de conexiones ADO.NET.
• Múltiples conexiones están dirigidas al mismo espacio de trabajo Fabric y al mismo refugio lacustre y utilizan configuraciones compatibles de Spark.
• Reducir el tiempo de inicio de la conexión y la provisión repetida de sesiones de Spark es importante.
• Tu carga de trabajo puede usar la capacidad compartida de Spark gestionada por el servidor, manteniendo la ejecución de las instrucciones aislada por REPL.

Usa el modo clásico cuando:

• Tu aplicación utiliza solo una o unas pocas conexiones duraderas.
• Cada conexión requiere una sesión dedicada de Spark para una carga de trabajo estricta o aislamiento de recursos.
• Las conexiones requieren configuraciones de Spark sustancialmente diferentes que no deberían compartir una sesión subyacente.
• El endpoint de Fabric Livy para el espacio de trabajo objetivo y la casa del lago no soporta el modo HC.

Cómo funcionan las conexiones HC

Cuando tu aplicación llama a Open o OpenAsync y no hay disponible ninguna conexión agrupada compatible, el controlador:

1. Solicita una sesión de HC a Fabric.
2. Espera a que la sesión esté lista, como máximo hasta que se agote el tiempo de espera de adquisición configurado.
3. Conecta la conexión ADO.NET con la sesión HC asignada y con el REPL.
4. Enruta comandos, consultas, solicitudes de cancelación y operaciones de limpieza a través de los endpoints HC.

Las sesiones de HC arrendadas por separado de forma simultánea utilizan REPLs independientes. Los comandos de una conexión comparten la sesión HC y el REPL de esa conexión.

El pooling del lado del cliente está habilitado por defecto. Cerrar o eliminar una conexión elegible normalmente devuelve su sesión HC física y su REPL al pool local de procesos para su reutilización; no necesariamente libera la asignación de forma remota. Con la agrupación de conexiones desactivada, al cerrar la conexión física se realiza la limpieza de HC. Sigue usando using instrucciones para que las conexiones lógicas respondan con rapidez.

Activar el modo HC

El modo HC es opcional. Si omites hcEnabled o lo estableces en false, el controlador usa la ruta de sesión clásica de Livy.

Establezca la propiedad hcEnabled en true para obtener una sesión de HC:

hcEnabled=true;

Configurar empaquetado de sesión

HcSessionTag proporciona una indicación del lado del servidor para agrupar sesiones HC compatibles en una sesión subyacente de Livy. Una etiqueta coincidente no garantiza la asignación a la misma sesión subyacente.

Si omites la etiqueta o proporcionas un valor vacío o que solo contenga espacios en blanco, el controlador no lo envía en la solicitud de adquisición. Omitir la etiqueta no desactiva el modo HC ni el empaquetado del lado de servicio. Establezca una etiqueta explícita cuando se deben considerar instancias o cargas de trabajo relacionadas para capacidad compartida. Utiliza una etiqueta operativa estable y no sensible, como reporting-service o nightly-etl. No incluyas secretos, tokens de acceso, datos personales, identificadores de clientes ni texto de consulta.

La configuración de Spark también afecta a la compatibilidad de la sesión. Usa HcConfOverrides para proporcionar las configuraciones de Spark incluidas en la lista de permitidas para crear sesiones de HC:

Server=https://api.fabric.microsoft.com;SparkServerType=Fabric;AuthFlow=AzureCli;HcEnabled=true;HcConfOverrides="spark.executor.memory=8g;spark.executor.cores=4";

Para múltiples anulaciones, indica el valor total HcConfOverrides . Un punto y coma sin comillas inicia otra propiedad externa de la cadena de conexión; no amplía HcConfOverrides. El analizador acepta valores entre comillas simples o dobles, conserva los puntos y coma y los signos de igual dentro de los valores entrecomillados, y descodifica las comillas coincidentes duplicadas ('' o ""). Se ignora el espacio en blanco alrededor de los nombres de propiedades y en los bordes exteriores de los valores sin comillas. Se conserva el espacio en blanco dentro de los valores sin comillas y todo el espacio en blanco dentro de los valores entre comillas. Los valores vacíos anulan los valores predeterminados del entorno, y gana la última propiedad duplicada.

También puedes dejar LivyConnectionStringBuilder que te encargues de las citas:

var builder = new Microsoft.Spark.Livy.AdoNet.LivyConnectionStringBuilder
{
    Server = "https://api.fabric.microsoft.com",
    SparkServerType = "Fabric",
    FabricWorkspaceID = "<workspace-id>",
    FabricLakehouseID = "<lakehouse-id>",
    AuthFlow = "AzureCli",
    HcEnabled = true,
    HcConfOverrides = "spark.executor.memory=8g;spark.executor.cores=4"
};

string connectionString = builder.ConnectionString;

Estos ejemplos requieren el controlador Microsoft ADO.NET versión 2.0.1 o posterior. Añade los identificadores del espacio de trabajo y del lakehouse antes de abrir una conexión. Ambas sobrescrituras se envían en la solicitud de create-session de HC como entradas conf separadas. Cada sobrescritura debe usar una de estas claves que distinguen entre mayúsculas y minúsculas:

• spark.sql.shuffle.partitions
• spark.executor.memory
• spark.executor.cores
• spark.driver.memory
• spark.sql.ansi.enabled
• spark.sql.legacy.timeParserPolicy
• spark.sql.session.timeZone
• livy.rsc.client.connect.timeout
• livy.rsc.server.idle-timeout

Las comillas mal formadas se rechazan sin incluir el contenido de la cadena de conexión en el error de análisis sintáctico.

Utiliza etiquetas y valores de configuración consistentes entre conexiones que estén pensadas para compartir capacidad. Fabric determina si una solicitud puede usar una sesión existente o si requiere otra sesión.

Configurar el tiempo de adquisición

Utiliza la siguiente configuración para controlar cuánto tiempo espera el controlador a que se inicie una sesión de HC:

Para la mayoría de las cargas de trabajo, mantén los valores por defecto. Aumente el tiempo de espera de adquisición solo cuando el inicio de la capacidad tarda habitualmente más de cinco minutos.

Usa el modo HC con agrupación de conexiones

El modo HC y el pooling de conexiones ADO.NET abordan diferentes capas:

• El modo HC gestiona la capacidad compartida de Fabric Spark y las sesiones de Livy en el servidor.
• La agrupación de conexiones ADO.NET reutiliza recursos de conexión gestionados por el controlador en la aplicación cliente.

Puedes activar ambas funciones. La agrupación de conexiones reduce la configuración repetida de conexiones en el lado del cliente, mientras que el modo HC reduce la provisión repetida de sesiones Spark en el lado del servidor. Dimensiona el pool de conexiones para la concurrencia esperada de la aplicación en lugar de usar un pool grande para crear trabajo paralelo innecesario.

En modo HC, AutoReconnect=true no vuelve a ejecutar de forma transparente un comando fallido tras un error de sesión obsoleta. La solicitud recibe la excepción y debe decidir si es seguro volver a intentar la operación.

Desactivar el modo HC

Para usar el modo clásico para nuevas conexiones, elimina HcEnabled de la cadena de conexión o configúrala en false:

HcEnabled=false

El cambio afecta a las nuevas conexiones y no vacía las sesiones HC agrupadas existentes. Cierra o elimina las conexiones lógicas normalmente; las sesiones físicas elegibles pueden permanecer en el grupo de clientes hasta que se retiren.

limitaciones de ADO.NET

• Las transacciones no están soportadas.
• Los comandos solo admiten el modo de comandos de texto. No se soportan los modos de procedimientos almacenados ni de comandos directos en tabla.
• Prepare no realiza ninguna acción.
• Un comando debe contener una sentencia; el texto de la orden de varias sentencias es rechazado.
• Utiliza conexiones separadas y simultáneamente abiertas para cargas de trabajo concurrentes. Los comandos de una conexión comparten la misma sesión y REPL.

Asignación de tipos de datos

El controlador asigna los tipos de datos de Spark SQL a tipos de .NET:

Trabajar con tipos complejos

La ruta de resultados HC no serializa de forma fiable los valores nativos anidados de ARRAY, MAP o STRUCT como JSON. Convertir valores complejos en cadenas JSON en Spark SQL antes de deserializarlos:

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

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

using var reader = await command.ExecuteReaderAsync();
if (await reader.ReadAsync())
{
    string arrayJson = reader.GetString(0);
    string mapJson = reader.GetString(1);
    string structJson = reader.GetString(2);

    var array = JsonSerializer.Deserialize<int[]>(arrayJson);
    var map = JsonSerializer.Deserialize<Dictionary<string, string>>(mapJson);
}

Solución de problemas

Esta sección ofrece orientación para resolver problemas comunes que puedas encontrar al usar el controlador Microsoft ADO.NET para Fabric Data Engineering.

Problemas comunes

En las secciones siguientes se describen problemas comunes y sus soluciones:

Fallos de conexión

Problema: No se puede conectar a Fabric

Soluciones:

1. Verifique que FabricWorkspaceID y FabricLakehouseID sean GUID correctos
2. Compruebe la autenticación de la CLI de Azure: az account show
3. Asegúrese de que tiene los permisos adecuados del área de trabajo de Fabric.
4. Comprobación de la conectividad de red a api.fabric.microsoft.com

Errores de autenticación

Problema: error de autenticación con la CLI de Azure

Soluciones:

• Ejecución az login para actualizar las credenciales
• Compruebe el inquilino correcto: az account set --subscription <subscription-id>
• Comprobar la validez del token: az account get-access-token --resource https://api.fabric.microsoft.com

Tiempos de espera de consulta agotados

Problema: Las consultas agotan el tiempo de espera en tablas grandes

Soluciones:

• Aumentar el tiempo de espera de la declaración: LivyStatementTimeoutSeconds=1200.
• Use la cláusula LIMIT para restringir el tamaño del resultado durante el desarrollo.
• Asegúrese de que el clúster de Spark tiene recursos adecuados

Tiempo de espera de conexión o de obtención de HC

Problema: Una conexión se agota mientras espera una conexión agrupada o una sesión HC

Soluciones:

• Para la espera del grupo de clientes y el establecimiento de la conexión HTTP, consulta HttpConnectionTimeoutInSeconds.
• Para la adquisición de HC, aumenta hcAcquireTimeoutSeconds dentro del intervalo admitido de entre 120 y 3.600 segundos.
• Comprobación de la disponibilidad de la capacidad de Fabric
• Verificar que el área de trabajo no haya alcanzado los límites de sesión

Habilitar registro

Al solucionar problemas, un registro detallado puede ayudarte a identificar la causa raíz. Configurar el registro a través de la cadena de conexión:

Para habilitar el registro detallado a través de la cadena de conexión:

LogLevel=Debug;LogFilePath=<path-to-log-file>

Si no configuras LogFilePath ni una configuración global de registro, el controlador escribe los registros en %LOCALAPPDATA%\FabricSparkAdoNet\Logs en Windows.

Niveles de registro:

• Trace: La máxima verbosidad, incluye todas las llamadas a la API.
• Debug: información detallada de depuración
• Information: información general (valor predeterminado)
• Warning: solo advertencias
• Error: solo errores

Contenido relacionado

• Runtimes de Apache Spark en Fabric
• Fabric Runtime 1.3
• ¿Qué es Livy API para ingeniería de datos?
• Controlador Microsoft JDBC para Fabric Data Engineering
• Controlador ODBC de Microsoft para Fabric Data Engineering