Usa Microsoft. Data.SqlClient en una app .NET

En este inicio rápido, creas una aplicación de consola .NET que:

Lee su cadena de conexión desde el entorno en lugar del código fuente.
Abre una conexión de forma asíncrona.
Crea una tabla si no existe.
Inserta una fila con un comando parametrizado.
Lee filas con una consulta parametrizada.
Gestiona errores de SQL y de cancelación.

El ejemplo utiliza Microsoft. Data.SqlClient 7.0.3, la versión estable actual.

Prerequisites

Necesitas el SDK .NET 10 o un SDK .NET compatible más adelante.

Creación de una base de datos SQL

Crea o conéctate a una base de datos SQL en una de las siguientes plataformas:

Creación de una base de datos SQL en cuestión de minutos mediante Azure Portal

El inicio rápido crea su propia tabla, así que no se requieren datos de ejemplo. La identidad de la base de datos necesita permiso para conectarse y crear, insertar y seleccionar de una tabla.

Para la base de datos SQL en Microsoft Fabric, copia los nombres del servidor y la base de datos del elemento de la base de datos SQL. No uses el endpoint de analítica SQL. La identidad necesita permiso para leer objetos, que puede proporcionar un permiso de rol de espacio de trabajo o de elemento. Para más información, véase Autenticación en base de datos SQL. No se soporta autenticación SQL.

Para Azure SQL Database, configura la autenticación y acceso a la base de datos de Microsoft Entra ID.

Creación del proyecto

Ejecute estos comandos:

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart
dotnet add package Microsoft.Data.SqlClient --version 7.0.3
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.0.3

El paquete de extensión proporciona modos de autenticación Microsoft Entra ID proporcionados por el controlador. Una aplicación que utilice solo autenticación integrada de Windows o autenticación SQL puede omitir Microsoft.Data.SqlClient.Extensions.Azure.

Configurar la conexión

Establece la SQL_CONNECTION_STRING variable de entorno para tu base de datos. No pongas una contraseña, un token de acceso ni una cadena de conexión de producción en el código fuente.

Elige uno de estos puntos de inicio y cambia los marcadores de posición.

Fabric SQL o Azure SQL con autenticación sin contraseña

Inicia sesión con una identidad en Microsoft Entra ID que tenga acceso a la base de datos. Para el desarrollo local, utiliza una herramienta de desarrollo como la CLI de Azure:

az login

Copia los nombres exactos de servidores y bases de datos desde el elemento de la base de datos SQL en Fabric o en la base de datos Azure SQL. Para PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Instrucciones para Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict;MultiSubnetFailover=true;Connect Timeout=30'

Para una aplicación alojada en Azure que se conecta a Azure SQL, concede acceso a la base de datos de identidad gestionada y luego usa Authentication=Active Directory Managed Identity. Para otras opciones de Microsoft Entra ID, véase autenticación de Microsoft Entra ID.

SQL Server sobre TCP

Utiliza el servidor, el puerto, la base de datos y el inicio de sesión desde tu SQL Server actual o la guía de configuración que has seguido. El siguiente ejemplo de autenticación SQL es para un contenedor de desarrollo local. Para PowerShell:

$env:SQL_CONNECTION_STRING = 'Server=tcp:<server>,1433;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Instrucciones para Bash:

export SQL_CONNECTION_STRING='Server=tcp:<server>,1433;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true;TrustServerCertificate=true;Connect Timeout=30'

Caution

TrustServerCertificate=true Salta la validación del certificado del servidor. Úsalo solo con una instancia de desarrollo local que no tenga un certificado de confianza. Para instancias compartidas o de producción de SQL Server, instala un certificado en el que el cliente confíe, utiliza el nombre del servidor en ese certificado y elimina TrustServerCertificate=true.

Si el entorno soporta autenticación integrada de Windows o Kerberos, sustituye User ID y Password por Integrated Security=true. Para los requisitos de configuración, véase autenticación de SQL Server.

Adición del código de la aplicación

Reemplace el contenido de Program.cs por el código siguiente:

using System.Data;
using Microsoft.Data.SqlClient;

string? connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING");

if (string.IsNullOrWhiteSpace(connectionString))
{
    Console.Error.WriteLine(
        "Set the SQL_CONNECTION_STRING environment variable.");
    return 1;
}

using var cancellation = new CancellationTokenSource();
Console.CancelKeyPress += (_, eventArgs) =>
{
    eventArgs.Cancel = true;
    cancellation.Cancel();
};

try
{
    await using var connection = new SqlConnection(connectionString);
    await connection.OpenAsync(cancellation.Token);

    const string createTableSql = """
        IF OBJECT_ID(N'dbo.SqlClientQuickstart', N'U') IS NULL
        BEGIN
            CREATE TABLE dbo.SqlClientQuickstart
            (
                Id int IDENTITY(1, 1) PRIMARY KEY,
                Message nvarchar(200) NOT NULL,
                CreatedAt datetimeoffset NOT NULL
                    CONSTRAINT DF_SqlClientQuickstart_CreatedAt
                    DEFAULT sysdatetimeoffset()
            );
        END;
        """;

    using (var createCommand =
        new SqlCommand(createTableSql, connection) { CommandTimeout = 30 })
    {
        await createCommand.ExecuteNonQueryAsync(cancellation.Token);
    }

    const string insertSql = """
        INSERT INTO dbo.SqlClientQuickstart (Message)
        OUTPUT INSERTED.Id
        VALUES (@message);
        """;

    int insertedId;
    using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        insertCommand.Parameters.Add(
            new SqlParameter("@message", SqlDbType.NVarChar, 200)
            {
                Value = "Hello from Microsoft.Data.SqlClient"
            });

        object? result =
            await insertCommand.ExecuteScalarAsync(cancellation.Token);
        insertedId = Convert.ToInt32(result);
    }

    const string querySql = """
        SELECT Id, Message, CreatedAt
        FROM dbo.SqlClientQuickstart
        WHERE Id = @id
        ORDER BY Id;
        """;

    using var queryCommand =
        new SqlCommand(querySql, connection) { CommandTimeout = 30 };
    queryCommand.Parameters.Add(
        new SqlParameter("@id", SqlDbType.Int) { Value = insertedId });

    await using SqlDataReader reader =
        await queryCommand.ExecuteReaderAsync(cancellation.Token);

    while (await reader.ReadAsync(cancellation.Token))
    {
        Console.WriteLine(
            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
            $"at {reader.GetDateTimeOffset(2):O}");
    }

    return 0;
}
catch (OperationCanceledException)
{
    Console.Error.WriteLine("The operation was canceled.");
    return 2;
}
catch (SqlException ex)
{
    Console.Error.WriteLine(
        $"SQL error {ex.Number}, connection {ex.ClientConnectionId}: " +
        ex.Message);
    return 3;
}

Los tipos y tamaños de parámetros coinciden con las columnas de la tabla. Los parámetros envían valores por separado del texto SQL, lo que impide que esos valores cambien la sintaxis de los comandos y ayuda a SQL Server a reutilizar los planes de consulta.

await using elimina el lector y la conexión incluso cuando ocurre una excepción. Eliminar la conexión devuelve su conexión física al pool de conexiones en lugar de mantener una conexión abierta durante toda la vida de la aplicación.

Ejecutar la aplicación

Ejecute la aplicación:

dotnet run

La aplicación imprime la fila que insertó:

1: Hello from Microsoft.Data.SqlClient at <timestamp>

El valor de identidad y la marca de tiempo varían en cada base de datos.

Si la conexión falla, utiliza el número de error SQL y el ID de conexión del cliente que aparecen en la salida de error. Comprueba los nombres de servidores y bases de datos, acceso a la red, permisos de base de datos, configuración de autenticación y configuración de certificados. No añadas TrustServerCertificate=true a una conexión de Azure SQL o de producción como solución general para problemas de conexión.

Utiliza el patrón en una aplicación

Mantén estos límites cuando muevas la muestra a una API, servicio, aplicación de escritorio o trabajador en segundo plano:

Carga la información de conexión a través del sistema de configuración de la aplicación.
Abre una conexión para una breve unidad de trabajo y luego ciérrala.
Pasa un CancellationToken a través de las llamadas a open, command y reader.
Establece tiempos de espera de comandos según la operación.
Usa parámetros para cada valor que provenga de fuera de la sentencia SQL.
Iniciar sesión SqlException.Number y ClientConnectionId sin registrar credenciales ni tokens de acceso.
Añadir reintentos solo para fallos transitorios y solo cuando repetir la operación es seguro.

Pasos siguientes

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-09-21