Conexión y consulta de Azure SQL Database mediante .NET y la biblioteca Microsoft.Data.SqlClient

  • Artículo

Se aplica a:Azure SQL Database

En este inicio rápido, se describe cómo conectar una aplicación a una base de datos en Azure SQL Database y realizar consultas mediante .NET y la biblioteca Microsoft.Data.SqlClient. En este inicio rápido se sigue el enfoque recomendado sin contraseña para conectarse a la base de datos. Puede consultar más información sobre las conexiones sin contraseña en Conexiones sin contraseña para servicios de Azure.

Requisitos previos

Configuración de la base de datos

Las conexiones seguras sin contraseña a Azure SQL Database requieren una cierta configuración de la base de datos. Compruebe la siguiente configuración en el servidor lógico de Azure para conectarse correctamente a Azure SQL Database tanto en el entorno local como en un entorno hospedado:

  1. En el caso de las conexiones de desarrollo local, asegúrese de que el servidor lógico está configurado para permitir que la dirección IP de la máquina local y otros servicios de Azure se conecten:

    • Vaya a la página Redes del servidor.

    • Active o desactive el botón de radio Redes seleccionadas para mostrar opciones de configuración adicionales.

    • Seleccione Agregar la dirección IPv4 de cliente (xx.xx.xx.xx) para agregar una regla de firewall que habilitará las conexiones desde la dirección IPv4 del equipo local. Como alternativa, también puede seleccionar + Agregar una regla de firewall para especificar una dirección IP específica de su elección.

    • Asegúrese de que la casilla Permitir que los servicios y recursos de Azure accedan a este servidor esté seleccionada.

      A screenshot showing how to configure firewall rules.

      Advertencia

      La habilitación de la opción Permitir que los servicios y recursos de Azure accedan a este servidor no es un procedimiento de seguridad recomendado para escenarios de producción. Las aplicaciones reales deben implementar enfoques más seguros, como restricciones de firewall más fuertes o configuraciones de red virtual.

      Puede consultar más información sobre las configuraciones de seguridad de la base de datos en los siguientes recursos:

  2. El servidor también debe tener habilitada la autenticación de Microsoft Entra y tener asignada una cuenta de administrador de Microsoft Entra. Para las conexiones de desarrollo local, la cuenta de administrador de Microsoft Entra debe ser una cuenta que también puede iniciar sesión en Visual Studio o en la CLI de Azure localmente. Puede comprobar si el servidor tiene habilitada la autenticación de Microsoft Entra en la página de Microsoft Entra ID del servidor lógico.

    A screenshot showing how to enable Microsoft Entra authentication.

  3. Si usa una cuenta personal de Azure, asegúrese de que ha instalado y configurado Microsoft Entra para Azure SQL Database con el fin de asignar su cuenta como administrador del servidor. Si usa una cuenta corporativa, es probable que Microsoft Entra ID ya esté configurado.

Creación del proyecto

Para los pasos siguientes, cree una aplicación API web mínima de .NET mediante la CLI de .NET o Visual Studio 2022.

  1. En el menú de Visual Studio, vaya a Archivo>Nuevo>Proyecto...

  2. En la ventana de diálogo, escriba ASP.NET en el cuadro de búsqueda de la plantilla de proyecto y seleccione el resultado de la API web de ASP.NET Core. Elija Siguiente en la parte inferior del cuadro de diálogo.

  3. En Nombre del proyecto, escriba DotNetSQL. Deje los valores predeterminados para el resto de los campos y seleccione Siguiente.

  4. En Plataforma, seleccione .NET 7.0 y desactive la opción Usar controladores (desactivar para usar API mínimas). En esta guía de inicio rápido se usa una plantilla de API mínima para simplificar la creación y configuración de puntos de conexión.

  5. Seleccione Create. El nuevo proyecto se abre en el entorno de Visual Studio.

Adición de la biblioteca Microsoft.Data.SqlClient

Para conectarse a Azure SQL Database mediante .NET, instale Microsoft.Data.SqlClient. Este paquete actúa como proveedor de datos para conectarse a bases de datos, ejecutar comandos y recuperar resultados.

Nota

Asegúrese de instalar Microsoft.Data.SqlClient y no System.Data.SqlClient. Microsoft.Data.SqlClient es una versión más reciente de la biblioteca cliente de SQL que proporciona funcionalidades adicionales.

  1. En la ventana Explorador de soluciones, haga clic con el botón derecho en el nodo Dependencias y seleccione Administrar paquetes NuGet.

  2. En la ventana resultante, busque SqlClient. Busque el resultado de Microsoft.Data.SqlClient y seleccione Instalar.

Configurar la cadena de conexión

Para el desarrollo local con conexiones sin contraseña a Azure SQL Database, agregue la siguiente sección ConnectionStrings al archivo appsettings.json. Reemplace los marcadores de posición <database-server-name> y <database-name> por sus propios valores.

"ConnectionStrings": {
    "AZURE_SQL_CONNECTIONSTRING": "Server=tcp:<database-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Authentication=\"Active Directory Default\";"
}

La cadena de conexión sin contraseña establece un valor de configuración de Authentication="Active Directory Default", que indica a la biblioteca Microsoft.Data.SqlClient que se conecte a Azure SQL Database mediante una clase denominada DefaultAzureCredential. DefaultAzureCredential permite conexiones sin contraseña a los servicios de Azure y la proporciona la biblioteca de identidades de Azure de la que depende la biblioteca cliente SQL. DefaultAzureCredential admite varios métodos de autenticación y determina qué método debe usarse en tiempo de ejecución para los diferentes entornos.

Por ejemplo, cuando la aplicación se ejecuta localmente, DefaultAzureCredential se autentica a través del usuario con el que ha iniciado sesión en Visual Studio, o en otras herramientas locales, como la CLI de Azure. Una vez que la aplicación se implementa en Azure, el mismo código detecta y aplica la identidad administrada asociada a la aplicación hospedada, que configurará más adelante. La introducción a la biblioteca de identidades de Azure explica el orden y las ubicaciones en las que DefaultAzureCredential busca las credenciales.

Nota

Las cadenas de conexión sin contraseña son seguras para confirmarlas en el control de código fuente, ya que no contienen secretos como nombres de usuario, contraseñas o claves de acceso.

Adición del código para conectarse a Azure SQL Database

Reemplace el contenido del archivo Program.cs por el código siguiente, el cual realiza los pasos importantes siguientes:

  • Recupera la cadena de conexión sin contraseña de appsettings.json.
  • Crea una tabla Persons en la base de datos durante el inicio (solo para escenarios de prueba).
  • Crea un punto de conexión HTTP GET para recuperar todos los registros almacenados en la tabla Persons.
  • Crea un punto de conexión HTTP POST para agregar registros nuevos a la tabla Persons.
using Microsoft.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// For production scenarios, consider keeping Swagger configurations behind the environment check
// if (app.Environment.IsDevelopment())
// {
    app.UseSwagger();
    app.UseSwaggerUI();
// }

app.UseHttpsRedirection();

string connectionString = app.Configuration.GetConnectionString("AZURE_SQL_CONNECTIONSTRING")!;

try
{
    // Table would be created ahead of time in production
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "CREATE TABLE Persons (ID int NOT NULL PRIMARY KEY IDENTITY, FirstName varchar(255), LastName varchar(255));",
        conn);
    using SqlDataReader reader = command.ExecuteReader();
}
catch (Exception e)
{
    // Table may already exist
    Console.WriteLine(e.Message);
}

app.MapGet("/Person", () => {
    var rows = new List<string>();

    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand("SELECT * FROM Persons", conn);
    using SqlDataReader reader = command.ExecuteReader();

    if (reader.HasRows)
    {
        while (reader.Read())
        {
            rows.Add($"{reader.GetInt32(0)}, {reader.GetString(1)}, {reader.GetString(2)}");
        }
    }

    return rows;
})
.WithName("GetPersons")
.WithOpenApi();

app.MapPost("/Person", (Person person) => {
    using var conn = new SqlConnection(connectionString);
    conn.Open();

    var command = new SqlCommand(
        "INSERT INTO Persons (firstName, lastName) VALUES (@firstName, @lastName)",
        conn);

    command.Parameters.Clear();
    command.Parameters.AddWithValue("@firstName", person.FirstName);
    command.Parameters.AddWithValue("@lastName", person.LastName);

    using SqlDataReader reader = command.ExecuteReader();
})
.WithName("CreatePerson")
.WithOpenApi();

app.Run();

Por último, agregue la clase Person a la parte inferior del archivo Program.cs. Esta clase representa un único registro en la tabla Persons de la base de datos.

public class Person
{
    public required string FirstName { get; set; }
    public required string LastName { get; set; }
}

Ejecución y prueba local de la aplicación

La aplicación está lista para probarse localmente. Asegúrese de que ha iniciado sesión en Visual Studio o en la CLI de Azure con la misma cuenta que ha establecido como administrador de la base de datos.

  1. Presione el botón Ejecutar en la parte superior de la ventana de Visual Studio para iniciar el proyecto de API.

  2. En la página de la interfaz de usuario de Swagger, expanda el método POST y seleccione Probar.

  3. Modifique el código JSON de ejemplo para incluir los valores de nombre y el apellido. Seleccione Ejecutar para agregar un nuevo registro a la base de datos. La API devuelve una respuesta correcta.

    A screenshot showing how to test the API.

  4. Expanda el método GET en la página de la interfaz de usuario de Swagger y seleccione Pruébelo. Elija Ejecutar y se devolverá la persona que acaba de crear.

Implementación en Azure App Service

La aplicación está lista para implementarse en Azure. Visual Studio puede crear una instancia de Azure App Service e implementar la aplicación en un único flujo de trabajo.

  1. Asegúrese de que la aplicación se detiene y se compila correctamente.

  2. En la ventana Explorador de soluciones de Visual Studio, haga clic con el botón derecho en el nodo de proyecto del nivel superior y seleccione Publicar.

  3. En el cuadro de diálogo de publicación, seleccione Azure como destino de implementación y, después, seleccione Siguiente.

  4. Para el destino específico, elija Azure App Service (Windows) y seleccione Siguiente.

  5. Seleccione el icono + para crear una nueva instancia de App Service para implementarla y escriba los siguientes valores:

    • Nombre: deje el valor predeterminado.

    • Nombre de la suscripción: seleccione la suscripción en la que se va a realizar la implementación.

    • Grupo de recursos: seleccione Nuevo y cree un grupo de recursos denominado msdocs-dotnet-sql.

    • Plan de hospedaje: seleccione Nuevo para abrir el cuadro de diálogo Plan de hospedaje. Deje los valores predeterminados como están y seleccione Aceptar.

    • Seleccione Crear para cerrar el cuadro de diálogo original. Visual Studio crea un recurso de App Service en Azure.

      A screenshot showing how to deploy with Visual Studio.

  6. Una vez que se crea el recurso, asegúrese de que está seleccionado en la lista de servicios de aplicaciones y, después, seleccione Siguiente.

  7. En el paso API Management, active la casilla Omitir este paso en la parte inferior y, a continuación, elija Finalizar.

  8. En el paso Finalizar, seleccione Cerrar si el cuadro de diálogo no se cierra automáticamente.

  9. Seleccione Publicar en la esquina superior derecha del resumen del perfil de publicación para implementar la aplicación en Azure.

Cuando finaliza la implementación, Visual Studio inicia el explorador para mostrar la aplicación hospedada, pero en este momento la aplicación no funciona correctamente en Azure. Todavía debe configurar la conexión segura entre la instancia de App Service y la base de datos SQL para recuperar los datos.

Conexión de App Service a Azure SQL Database

Los pasos siguientes son necesarios para crear una conexión sin contraseña entre la instancia de App Service y Azure SQL Database:

  1. Cree una identidad administrada para App Service. La biblioteca Microsoft.Data.SqlClient incluida en la aplicación detectará automáticamente la identidad administrada, al igual que detectó el usuario local de Visual Studio.
  2. Cree un usuario de SQL Database y asócielo a la identidad administrada de App Service.
  3. Asigne roles de SQL al usuario de la base de datos que le concedan permisos de lectura, escritura y quizá otros permisos.

Hay varias herramientas disponibles para implementar estos pasos:

El conector de servicio es una herramienta que simplifica las conexiones autenticadas entre distintos servicios de Azure. Actualmente, el conector de servicio admite la conexión de una instancia de App Service a una base de datos SQL a través de la CLI de Azure, con el comando az webapp connection create sql. Este único comando completa los tres pasos mencionados anteriormente.

az webapp connection create sql \
    -g <app-service-resource-group> \
    -n <app-service-name> \
    --tg <database-server-resource-group> \
    --server <database-server-name> \
    --database <database-name> \
    --system-identity

Puede comprobar los cambios realizados por el conector de servicio en la configuración de App Service.

  1. Vaya a la página Identidad de la instancia de App Service. En la pestaña Asignado por el sistema, el Estado debe establecerse en Activado. Este valor significa que se habilitó una identidad administrada asignada por el sistema para la aplicación.

  2. Vaya a la página Configuración de la instancia de App Service. En la pestaña Cadenas de conexión, debe aparecer la cadena de conexión AZURE_SQL_CONNECTIONSTRING. Seleccione el texto Haga clic aquí para mostrar el valor para ver la cadena de conexión sin contraseña que se ha generado. El nombre de esta cadena de conexión coincide con el que configuró en la aplicación, por lo que se detectará automáticamente al ejecutarse en Azure.

Importante

Aunque esta solución proporciona un enfoque sencillo para empezar, no es un procedimiento recomendado para entornos de producción. En esos escenarios, la aplicación no debe realizar todas las operaciones con una única identidad con privilegios elevados. Debe intentar implementar el principio de privilegios mínimos configurando varias identidades con permisos específicos para tareas específicas.

Puede consultar más información sobre cómo configurar roles de base de datos y seguridad en los siguientes recursos:

Prueba de la aplicación implementada

  1. Seleccione el botón Examinar en la parte superior de la página de información general de App Service para iniciar la dirección URL raíz de la aplicación.

  2. Anexe la ruta de acceso /swagger/index.html a la dirección URL para cargar la misma página de prueba de Swagger que usó localmente.

  3. Ejecute solicitudes GET y POST de prueba para comprobar que los puntos de conexión funcionan según lo previsto.

Sugerencia

Si recibe un error del servidor interno 500 durante las pruebas, puede deberse a las configuraciones de red de la base de datos. Compruebe que el servidor lógico está configurado con los valores descritos en la sección Configurar la base de datos.

¡Enhorabuena! La aplicación ahora está conectada a Azure SQL Database en entornos locales y hospedados.

Limpiar los recursos

Cuando haya terminado de trabajar con Azure SQL Database, elimine el recurso para evitar costos no previstos.

  1. En la barra de búsqueda de Azure Portal, busque Azure SQL y seleccione el resultado coincidente.

  2. Busque y seleccione la base de datos en la lista de bases de datos.

  3. En la página Información general de Azure SQL Database, seleccione Eliminar.

  4. En la página Está seguro de que quiere eliminar… de Azure que se abre, escriba el nombre de la base de datos para confirmar y, después, seleccione Eliminar.