Inicio rápido: Conéctate y consulta con Microsoft.Data.SqlClient

En este inicio rápido, creará una aplicación de consola .NET con Microsoft.Data.SqlClient 7.1.1.

Empiezas con una carpeta vacía, el SDK .NET y una base de datos de SQL Server o Azure SQL a la que puedes acceder desde tu ordenador. Terminas con una app de consola que crea una tabla, inserta dos filas con parámetros y las lee de vuelta.

Durante el proceso, la aplicación:

Lee su cadena de conexión desde una variable de entorno en lugar del código fuente.
Abre una conexión de forma asíncrona.
Utiliza parámetros para cada valor que envía a la base de datos.
Gestiona los errores SQL y las cancelaciones.

Para integrar el mismo acceso a datos en una API web, consulta Inicio rápido: Usa Microsoft.Data.SqlClient en una aplicación ASP.NET Core. Utiliza la misma tabla.

Prerequisites

El SDK de .NET 10 o un SDK de .NET posterior compatible. El SDK funciona en Windows, Linux y macOS. El SDK también compila la versión de .NET Framework del ejemplo, que solo funciona en Windows y necesita .NET Framework 4.8.1. Usa la versión .NET para nuevos desarrollos.
Un editor de código. Puedes usar Visual Studio, Visual Studio Code o cualquier editor junto con la interfaz de línea de comandos de .NET. Este artículo utiliza la .NET CLI.
Una base de datos a la que puedas conectarte. Si no tienes uno, crea uno usando las siguientes opciones.

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

Permisos de base de datos

La app crea su propia tabla, así que no necesitas datos de muestra. 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.

En una carpeta vacía, ejecuta estos comandos:

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

La plantilla de consola no ofrece objetivos para .NET Framework. En una carpeta vacía, crea el proyecto:

dotnet new console --framework net10.0 --name SqlClientQuickstart
cd SqlClientQuickstart

Sustituye el contenido de SqlClientQuickstart.csproj por este archivo de proyecto:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net481</TargetFramework>
  </PropertyGroup>

</Project>

Luego añade los paquetes:

dotnet add package Microsoft.Data.SqlClient --version 7.1.1
dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version 7.1.1

El paquete de extensión suministra los modos de autenticación Microsoft Entra del controlador, como Active Directory Default. Si tu aplicación solo usa autenticación SQL o autenticación integrada en Windows, puedes omitir Microsoft.Data.SqlClient.Extensions.Azure. Cuando uses ambos paquetes, mantén sus versiones iguales. Para otras opciones de instalación, consulta Instalación, actualización e implementación de Microsoft.Data.SqlClient.

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.

Azure SQL o base de datos SQL en Fabric con Microsoft Entra ID

Inicia sesión con una identidad de Microsoft Entra 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 la base de datos Azure SQL o el ítem de la base de datos SQL en Fabric. 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, concede a su identidad administrada acceso a la base de datos y luego usa Authentication=Active Directory Managed Identity. Para otras opciones, consulta la autenticación Microsoft Entra con Microsoft.Data.SqlClient.

SQL Server con autenticación SQL

Utiliza el servidor, el puerto, la base de datos y el inicio de sesión de tu instancia de SQL Server. El siguiente ejemplo es para una instancia de desarrollo local que no tiene un certificado de confianza. 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. Para obtener más información, consulte Cifrado y validación de certificados en Microsoft.Data.SqlClient.

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

Agregar el código

.NET
.NET Framework

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

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

    string[] messages =
    [
        "Hello from Microsoft.Data.SqlClient",
        "Parameters keep values out of the SQL text"
    ];

    int firstId = 0;
    await using (var insertCommand =
        new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
    {
        SqlParameter messageParameter =
            insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

        foreach (string message in messages)
        {
            messageParameter.Value = message;
            int id = (int)(await insertCommand.ExecuteScalarAsync(
                cancellation.Token))!;
            Console.WriteLine($"Inserted row {id}.");
            firstId = firstId == 0 ? id : firstId;
        }
    }

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

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

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

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

    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);
    if (ex.InnerException is not null)
    {
        Console.Error.WriteLine(ex.InnerException.Message);
    }
    return 3;
}

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

using System;
using System.Data;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task<int> Main()
    {
        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 += (sender, eventArgs) =>
            {
                eventArgs.Cancel = true;
                cancellation.Cancel();
            };

            try
            {
                await RunAsync(connectionString, cancellation.Token);
                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);
                if (ex.InnerException != null)
                {
                    Console.Error.WriteLine(ex.InnerException.Message);
                }
                return 3;
            }
        }
    }

    static async Task RunAsync(string connectionString, CancellationToken token)
    {
        using (var connection = new SqlConnection(connectionString))
        {
            await connection.OpenAsync(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(token);
            }

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

            string[] messages =
            {
                "Hello from Microsoft.Data.SqlClient",
                "Parameters keep values out of the SQL text"
            };

            int firstId = 0;
            using (var insertCommand =
                new SqlCommand(insertSql, connection) { CommandTimeout = 30 })
            {
                SqlParameter messageParameter =
                    insertCommand.Parameters.Add("@message", SqlDbType.NVarChar, 200);

                foreach (string message in messages)
                {
                    messageParameter.Value = message;
                    int id = (int)await insertCommand.ExecuteScalarAsync(token);
                    Console.WriteLine($"Inserted row {id}.");
                    firstId = firstId == 0 ? id : firstId;
                }
            }

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

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

                using (SqlDataReader reader =
                    await queryCommand.ExecuteReaderAsync(token))
                {
                    while (await reader.ReadAsync(token))
                    {
                        Console.WriteLine(
                            $"{reader.GetInt32(0)}: {reader.GetString(1)} " +
                            $"(created {reader.GetDateTimeOffset(2):u})");
                    }
                }
            }
        }
    }
}

Ejecuta la aplicación

Ejecute la aplicación:

dotnet run

La primera vez que ejecutas la app, la tabla está vacía y la salida es la siguiente:

Inserted row 1.
Inserted row 2.
1: Hello from Microsoft.Data.SqlClient (created 2026-10-20 20:56:10Z)
2: Parameters keep values out of the SQL text (created 2026-10-20 20:56:10Z)

Tus marcas de tiempo varían. Cada partida posterior añade dos filas más, por lo que los IDs continúan desde la última partida.

Si la app no puede conectarse, imprime el número de error SQL, el ID de conexión del cliente, el mensaje de error y el mensaje de excepción interna, y luego sale con el código 3. Para errores comunes, consulta Solución de problemas.

Funcionamiento del código

OpenAsync, ReadAsync, CancellationToken, ExecuteReaderAsync y ExecuteScalarAsync todos reciben el mismo ExecuteNonQueryAsync. Pulsa Ctrl+C para cancelar el trabajo en curso.
El comando insert se crea una vez y se ejecuta una vez para cada mensaje. Solo cambia el valor del parámetro.
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 el comando y ayuda a SQL Server a reutilizar los planes de consulta.
OUTPUT INSERTED.Id devuelve el nuevo valor de identidad, por lo que ExecuteScalarAsync devuelve el ID sin una segunda consulta.
await using libera los comandos, el lector y la conexión, incluso cuando ocurre una excepción. Liberar la conexión la devuelve al pool de conexiones. La versión de .NET Framework utiliza bloques using, porque estos tipos no implementan IAsyncDisposable en .NET Framework.
SqlException.Number identifica el error y ClientConnectionId te permite comparar un fallo del cliente con los registros del lado del servidor. Para fallos de conexión en Linux y macOS, la causa suele encontrarse únicamente en InnerException, como un fallo de validación de certificado detrás del genérico error: 35 - An internal exception was caught.

Troubleshoot

Error o síntoma	Elementos que se deben comprobar	Más información
`The certificate chain was issued by an authority that is not trusted`En Windows. En Linux y macOS, `error: 35 - An internal exception was caught`, seguido de la excepción interna `Certificate failed chain validation` con `UntrustedRoot`.	El certificado del servidor no es de confianza para el cliente, o el nombre del servidor en la cadena de conexión no coincide con el certificado. Instala un certificado de confianza. Úsalo `TrustServerCertificate=true` solo con una instancia de desarrollo local.	Cifrado y validación de certificados en Microsoft. Data.SqlClient
`SQL error 18456` con `Login failed for user`	El nombre de usuario, contraseña o nombre de base de datos es incorrecto, o el inicio de sesión no tiene acceso a la base de datos. Para Microsoft Entra ID, comprueba que la identidad se haya añadido como usuario de base de datos.	Guía de solución de problemas de SqlClient
`A network-related or instance-specific error occurred` con `error: 26`, `error: 40`o `The wait operation timed out`. En Linux y macOS, un tiempo de espera muestra `SQL error 258` con `error: 35`, seguido de la excepción interna `The connection attempt timed out`.	El nombre del servidor o puerto es incorrecto, el servidor no acepta conexiones TCP remotas o un cortafuegos bloquea el puerto. Para Azure SQL, revisa las reglas del firewall del servidor.	Guía de solución de problemas de SqlClient
`System.ArgumentException: Cannot find an authentication provider for 'ActiveDirectoryDefault'`	La cadena de conexión utiliza un modo de autenticación `Active Directory`, pero el proyecto no hace referencia a `Microsoft.Data.SqlClient.Extensions.Azure`. Añade el paquete con la misma versión que `Microsoft.Data.SqlClient`.	La autenticación Microsoft Entra pasa a un paquete de extensiones en la 7.0
`CS0234: The type or namespace name 'Data' does not exist in the namespace 'Microsoft'`	El proyecto no hace referencia al paquete `Microsoft.Data.SqlClient`. Ejecuta el `dotnet add package` comando desde la carpeta que contiene el archivo del proyecto.	Instalar, actualizar y desplegar Microsoft. Data.SqlClient
Informes de restauración `NU1902` o `NU1903` para un paquete transitivo	Un paquete del que depende el controlador tiene un aviso publicado.	Acciones cuando se reportan paquetes con vulnerabilidades conocidas

Limpieza de recursos

La tabla permanece en tu base de datos después de que la app se cierre. Si no planeas continuar con el inicio rápido de ASP.NET Core, que usa la misma tabla, elimínala con cualquier herramienta de consulta:

DROP TABLE IF EXISTS dbo.SqlClientQuickstart;

Luego borra la carpeta del proyecto. Desde la carpeta superior, para PowerShell:

Remove-Item -Recurse -Force SqlClientQuickstart

Instrucciones para Bash:

rm -rf SqlClientQuickstart

Borra la variable de entorno para que la cadena de conexión no se quede en tu sesión de shell. Para PowerShell, ejecuta Remove-Item Env:\SQL_CONNECTION_STRING. Para Bash, corre unset SQL_CONNECTION_STRING.

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 proceso en segundo plano:

Carga la información de conexión a través del sistema de configuración de la app.
Abra una conexión para una unidad de trabajo breve y luego ciérrela.
Pase un CancellationToken a través de llamadas abiertas, de comandos y de lector.
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

Resultoulle útil esta páxina?

Última actualización o 2026-10-23

Inicio rápido: Conéctate y consulta con Microsoft.Data.SqlClient

Prerequisites

Creación de una base de datos SQL

Permisos de base de datos

Creación del proyecto

Configurar la conexión

Azure SQL o base de datos SQL en Fabric con Microsoft Entra ID

SQL Server con autenticación SQL

Agregar el código

Ejecuta la aplicación

Funcionamiento del código

Troubleshoot

Limpieza de recursos

Utiliza el patrón en una aplicación

Pasos siguientes

Comentarios

Recursos adicionais