Código QR .NET Core: Leer y generar códigos QR en C#

¿Cómo se instala la biblioteca de códigos QR?

La instalación de IronQR a través de NuGet se realiza en cuestión de segundos. Abre Visual Studio, ve a Herramientas > Administrador de paquetes NuGet > Administrar paquetes NuGet para la solución, busca IronQR y haz clic en Instalar. El paquete tiene unas dependencias mínimas y está preparado para funcionar en Windows, macOS y Linux desde el primer momento.

Install-Package IronQR

IronQR está destinado a .NET Core 6, 7, 8, 9 y 10, así como a .NET Framework 4.6.2 y versiones posteriores. Para proyectos multiplataforma, una integración de SkiaSharp se encarga del procesamiento de imágenes en entornos de ejecución que no sean Windows. La biblioteca funciona con aplicaciones web ASP.NET Core, aplicaciones de consola y soluciones de escritorio sin necesidad de configuración adicional del tiempo de ejecución. Una vez instalada, todos los métodos de extensión y tipos necesarios están disponibles de inmediato.

El contexto español: QR obligatorio en cada factura

Antes de explorar los aspectos técnicos, es fundamental entender por qué la generación de QR es prioritaria para cualquier empresa que opere en España:

VeriFactu (AEAT): Bajo el sistema VeriFactu, cada factura emitida en España debe incluir un código QR que codifica el hash de la factura y apunta a https://sede.agenciatributaria.gob.es/ para verificación. Este QR debe mostrar el texto VERI*FACTU (con asterisk obligatorio) o la leyenda alternativa Factura verificable en la sede electrónica de la AEAT. IronQR permite generar este QR con el nivel de corrección de errores adecuado para garantizar su legibilidad en documentos impresos.

TicketBAI (Bizkaia, Gipuzkoa, Araba): Las tres diputaciones forales del País Vasco exigen el sistema TicketBAI para todos los comercios y autónomos de la región. Cada ticket de venta debe incluir un QR XAdES-firmado con la cadena de referencia de la factura. El esquema BATUZ (Bizkaia) difiere ligeramente de los de Gipuzkoa y Araba, pero todos requieren generación programática de QR. IronQR proporciona las herramientas necesarias para generar estos QR con el nivel de corrección y las dimensiones adecuadas.

Crea y Crece: La Ley 18/2022 (Crea y Crece) establecerá la obligación de factura electrónica B2B, que incluirá QR de verificación para todas las facturas entre empresas, con plazos de implantación que afectarán a la mayoría de empresas españolas a partir de 2027-2028.

¿Cómo se lee un código QR básico a partir de una imagen?

La lectura de datos de códigos QR a partir de archivos de imagen solo requiere unas pocas líneas de código. La clase QrReader utiliza un modelo avanzado de aprendizaje automático que evalúa la calidad de la imagen y selecciona automáticamente el modo de segmento correcto, lo que le proporciona resultados precisos incluso cuando la imagen de entrada no es ideal.

using IronQr;
using IronSoftware.Drawing;

// Load image containing QR code
var inputBmp = AnyBitmap.FromFile("qr-sample.png");
// Create QrImageInput from the bitmap
QrImageInput imageInput = new QrImageInput(inputBmp);
// Initialize QR Reader with ML model
QrReader reader = new QrReader();
// Read and decode all QR codes in the image
IEnumerable<QrResult> results = reader.Read(imageInput);
// Output decoded text strings
foreach (var qrCode in results)
{
    Console.WriteLine($"QR Code Value: {qrCode.Value}");
    Console.WriteLine($"URL: {qrCode.Url}");
}

using IronQr;
using IronSoftware.Drawing;

// Load image containing QR code
var inputBmp = AnyBitmap.FromFile("qr-sample.png");
// Create QrImageInput from the bitmap
QrImageInput imageInput = new QrImageInput(inputBmp);
// Initialize QR Reader with ML model
QrReader reader = new QrReader();
// Read and decode all QR codes in the image
IEnumerable<QrResult> results = reader.Read(imageInput);
// Output decoded text strings
foreach (var qrCode in results)
{
    Console.WriteLine($"QR Code Value: {qrCode.Value}");
    Console.WriteLine($"URL: {qrCode.Url}");
}

Imports IronQr
Imports IronSoftware.Drawing

' Load image containing QR code
Dim inputBmp = AnyBitmap.FromFile("qr-sample.png")
' Create QrImageInput from the bitmap
Dim imageInput As New QrImageInput(inputBmp)
' Initialize QR Reader with ML model
Dim reader As New QrReader()
' Read and decode all QR codes in the image
Dim results As IEnumerable(Of QrResult) = reader.Read(imageInput)
' Output decoded text strings
For Each qrCode In results
    Console.WriteLine($"QR Code Value: {qrCode.Value}")
    Console.WriteLine($"URL: {qrCode.Url}")
Next

¿Cómo se extraen los datos de un código QR avanzado?

Más allá de la decodificación básica de valores, IronQR expone coordenadas, segmentos de datos sin procesar e información a nivel de módulo de cada símbolo escaneado. Esto es esencial para los flujos de trabajo de procesamiento de documentos en los que es necesario saber exactamente dónde aparece un código QR en la página, o para aplicaciones que deben gestionar varios códigos en una sola imagen.

using IronQr;
using IronSoftware.Drawing;

var inputBmp = AnyBitmap.FromFile("document-with-qr.png");
QrImageInput imageInput = new QrImageInput(inputBmp);
QrReader reader = new QrReader();
IEnumerable<QrResult> results = reader.Read(imageInput);
foreach (var qrCode in results)
{
    // Access decoded value
    Console.WriteLine($"Data: {qrCode.Value}");
    // Get corner coordinate positions
    foreach (PointF point in qrCode.Points)
    {
        Console.WriteLine($"Position: {point.X}, {point.Y}");
    }
}

using IronQr;
using IronSoftware.Drawing;

var inputBmp = AnyBitmap.FromFile("document-with-qr.png");
QrImageInput imageInput = new QrImageInput(inputBmp);
QrReader reader = new QrReader();
IEnumerable<QrResult> results = reader.Read(imageInput);
foreach (var qrCode in results)
{
    // Access decoded value
    Console.WriteLine($"Data: {qrCode.Value}");
    // Get corner coordinate positions
    foreach (PointF point in qrCode.Points)
    {
        Console.WriteLine($"Position: {point.X}, {point.Y}");
    }
}

Imports IronQr
Imports IronSoftware.Drawing

Dim inputBmp = AnyBitmap.FromFile("document-with-qr.png")
Dim imageInput As New QrImageInput(inputBmp)
Dim reader As New QrReader()
Dim results As IEnumerable(Of QrResult) = reader.Read(imageInput)

For Each qrCode In results
    ' Access decoded value
    Console.WriteLine($"Data: {qrCode.Value}")
    ' Get corner coordinate positions
    For Each point As PointF In qrCode.Points
        Console.WriteLine($"Position: {point.X}, {point.Y}")
    Next
Next

¿Cómo afectan los niveles de corrección de errores a la calidad de los códigos QR?

La corrección de errores es el mecanismo que permite a un escáner de códigos QR recuperar los datos originales incluso cuando parte del código está oculto, mal impreso o físicamente dañado. El estándar del código QR define cuatro niveles —Bajo (L), Medio (M), Cuartil (Q) y Alto (H)—, cada uno de los cuales equilibra la capacidad de almacenamiento con la tolerancia a daños.

Para los QR de verificación VeriFactu y TicketBAI, se recomienda el nivel M o Q: M proporciona la densidad de datos suficiente para codificar el hash de la factura y la URL de verificación de la AEAT, mientras que Q ofrece mayor tolerancia para QR impresos en papel de baja calidad o escaneados con iluminación irregular. Para tickets de punto de venta con mayor densidad de datos, Q garantiza la legibilidad incluso con impresoras térmicas de resolución media.

Al generar códigos QR, especificar un nivel de corrección de errores más alto garantiza que el resultado se mantenga en condiciones reales de escaneo:

using IronQr;
using IronSoftware.Drawing;

// Configure QR options with high error correction
var qrOptions = new QrOptions(QrErrorCorrectionLevel.High, 20);
// Generate a QR code with specified error correction
QrCode myQr = QrWriter.Write("https://ironsoftware.com", qrOptions);
// Save as PNG image
AnyBitmap qrImage = myQr.Save();
qrImage.SaveAs("high-error-correction-qr.png");

using IronQr;
using IronSoftware.Drawing;

// Configure QR options with high error correction
var qrOptions = new QrOptions(QrErrorCorrectionLevel.High, 20);
// Generate a QR code with specified error correction
QrCode myQr = QrWriter.Write("https://ironsoftware.com", qrOptions);
// Save as PNG image
AnyBitmap qrImage = myQr.Save();
qrImage.SaveAs("high-error-correction-qr.png");

IRON VB CONVERTER ERROR developers@ironsoftware.com

¿Cómo se generan códigos QR con caracteres internacionales?

IronQR es compatible con toda la gama de modos de codificación QR: numérico, alfanumérico, byte y kanji. Para el texto en japonés y otros contenidos Unicode, la biblioteca selecciona automáticamente la codificación que ocupa menos espacio:

using IronQr;
using IronSoftware.Drawing;

// Generate QR that encodes Japanese Unicode text
QrCode japaneseQr = QrWriter.Write("こんにちは世界");
// The library selects Kanji mode automatically
AnyBitmap qrImage = japaneseQr.Save();
qrImage.SaveAs("japanese-qr.png");

using IronQr;
using IronSoftware.Drawing;

// Generate QR that encodes Japanese Unicode text
QrCode japaneseQr = QrWriter.Write("こんにちは世界");
// The library selects Kanji mode automatically
AnyBitmap qrImage = japaneseQr.Save();
qrImage.SaveAs("japanese-qr.png");

Imports IronQr
Imports IronSoftware.Drawing

' Generate QR that encodes Japanese Unicode text
Dim japaneseQr As QrCode = QrWriter.Write("こんにちは世界")
' The library selects Kanji mode automatically
Dim qrImage As AnyBitmap = japaneseQr.Save()
qrImage.SaveAs("japanese-qr.png")

¿Cómo se utilizan los generadores de carga útil para datos QR estructurados?

Un código QR que codifica una URL simple sirve para compartir enlaces de forma sencilla, pero muchas aplicaciones necesitan codificar datos estructurados: credenciales de WiFi, tarjetas de contacto en formato vCard o datos de eventos. Formatear estos datos manualmente es propenso a errores; Un punto y coma que falte o un orden incorrecto de los campos hará que los escáneres malinterpreten los datos.

IronQR proporciona ayudantes de carga útil que construyen estas cadenas estructuradas correctamente:

using IronQr;
using IronSoftware.Drawing;

// Generate QR code with URL payload
var urlQrCode = QrWriter.Write("https://ironsoftware.com/csharp/qr/");
// Save QR as PNG image file
AnyBitmap qrImage = urlQrCode.Save();
qrImage.SaveAs("url-qr-code.png");
Console.WriteLine("QR code generated successfully.");

using IronQr;
using IronSoftware.Drawing;

// Generate QR code with URL payload
var urlQrCode = QrWriter.Write("https://ironsoftware.com/csharp/qr/");
// Save QR as PNG image file
AnyBitmap qrImage = urlQrCode.Save();
qrImage.SaveAs("url-qr-code.png");
Console.WriteLine("QR code generated successfully.");

Imports IronQr
Imports IronSoftware.Drawing

' Generate QR code with URL payload
Dim urlQrCode = QrWriter.Write("https://ironsoftware.com/csharp/qr/")
' Save QR as PNG image file
Dim qrImage As AnyBitmap = urlQrCode.Save()
qrImage.SaveAs("url-qr-code.png")
Console.WriteLine("QR code generated successfully.")

¿Cómo se personaliza el aspecto de los códigos QR?

IronQR te permite controlar el aspecto visual de los códigos generados sin sacrificar la legibilidad. Puede cambiar los colores de primer plano y de fondo, aplicar una imagen de marca personalizada o insertar un logotipo en la zona libre del centro.

using IronQr;
using IronSoftware.Drawing;

// Define custom colors for the QR code
var darkColor = Color.FromArgb(30, 30, 120);   // Deep navy foreground
var lightColor = Color.White;

var options = new QrOptions(QrErrorCorrectionLevel.High, maxVersion: 20)
{
    BackgroundColor = lightColor,
    Color = darkColor,
    // Embed a logo image into the QR center
    Logo = AnyBitmap.FromFile("logo.png")
};

QrCode styledQr = QrWriter.Write("https://ironsoftware.com/csharp/qr/", options);
AnyBitmap output = styledQr.Save();
output.SaveAs("branded-qr.png");

using IronQr;
using IronSoftware.Drawing;

// Define custom colors for the QR code
var darkColor = Color.FromArgb(30, 30, 120);   // Deep navy foreground
var lightColor = Color.White;

var options = new QrOptions(QrErrorCorrectionLevel.High, maxVersion: 20)
{
    BackgroundColor = lightColor,
    Color = darkColor,
    // Embed a logo image into the QR center
    Logo = AnyBitmap.FromFile("logo.png")
};

QrCode styledQr = QrWriter.Write("https://ironsoftware.com/csharp/qr/", options);
AnyBitmap output = styledQr.Save();
output.SaveAs("branded-qr.png");

Imports IronQr
Imports IronSoftware.Drawing

' Define custom colors for the QR code
Dim darkColor As Color = Color.FromArgb(30, 30, 120) ' Deep navy foreground
Dim lightColor As Color = Color.White

Dim options As New QrOptions(QrErrorCorrectionLevel.High, maxVersion:=20) With {
    .BackgroundColor = lightColor,
    .Color = darkColor,
    ' Embed a logo image into the QR center
    .Logo = AnyBitmap.FromFile("logo.png")
}

Dim styledQr As QrCode = QrWriter.Write("https://ironsoftware.com/csharp/qr/", options)
Dim output As AnyBitmap = styledQr.Save()
output.SaveAs("branded-qr.png")

La inclusión de un logotipo reduce el área efectiva de datos, por lo que la biblioteca requiere un nivel de corrección de errores H cuando se proporciona un logotipo. La zona tranquila reservada en el centro ocupa aproximadamente el 30 % de la superficie del código, lo que se encuentra dentro de la capacidad de recuperación del nivel H. La biblioteca aplica esta restricción automáticamente: si se establece un nivel de corrección de errores más bajo junto con un logotipo, IronQR genera una excepción con un mensaje descriptivo en lugar de producir un código que se escanea de forma poco fiable.

Nota para QR VeriFactu y TicketBAI: Los QR de cumplimiento normativo no deben incluir logotipos incrustados, ya que las normativas de la AEAT y las diputaciones forales exigen máxima legibilidad. Reserve la personalización visual para QR de marketing y uso general.

Para aplicaciones ASP.NET Core, el tutorial del generador de códigos QR de .NET Core muestra cómo servir los códigos QR generados como respuestas de imagen desde una acción del controlador. El flujo de salida escribe directamente en la respuesta sin E/S de archivos intermedios, lo que mantiene baja la latencia para los puntos finales de alto tráfico.

¿Cómo se leen los códigos QR en una aplicación ASP.NET Core?

El escaneo de códigos QR del lado del servidor —a partir de imágenes cargadas, procesos de procesamiento de documentos o sistemas de inspección automatizados— es un caso de uso habitual de la API de lectura. En España, la verificación de facturas VeriFactu recibidas de proveedores puede automatizarse escaneando el QR de la factura y validando el hash contra la sede electrónica de la AEAT. La guía del escáner de códigos QR de ASP.NET cubre la configuración completa del controlador y del servicio, pero el patrón de lectura básico es el mismo que el de una aplicación de consola:

using IronQr;
using IronSoftware.Drawing;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/qr")]
public class QrScanController : ControllerBase
{
    [HttpPost("scan")]
    public IActionResult Scan(IFormFile imageFile)
    {
        using var stream = imageFile.OpenReadStream();
        var bitmap = AnyBitmap.FromStream(stream);
        var imageInput = new QrImageInput(bitmap);
        var reader = new QrReader();
        var results = reader.Read(imageInput);

        var decoded = results.Select(r => new { r.Value, r.Url }).ToList();
        return Ok(decoded);
    }
}

using IronQr;
using IronSoftware.Drawing;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/qr")]
public class QrScanController : ControllerBase
{
    [HttpPost("scan")]
    public IActionResult Scan(IFormFile imageFile)
    {
        using var stream = imageFile.OpenReadStream();
        var bitmap = AnyBitmap.FromStream(stream);
        var imageInput = new QrImageInput(bitmap);
        var reader = new QrReader();
        var results = reader.Read(imageInput);

        var decoded = results.Select(r => new { r.Value, r.Url }).ToList();
        return Ok(decoded);
    }
}

Imports IronQr
Imports IronSoftware.Drawing
Imports Microsoft.AspNetCore.Mvc

<ApiController>
<Route("api/qr")>
Public Class QrScanController
    Inherits ControllerBase

    <HttpPost("scan")>
    Public Function Scan(imageFile As IFormFile) As IActionResult
        Using stream = imageFile.OpenReadStream()
            Dim bitmap = AnyBitmap.FromStream(stream)
            Dim imageInput = New QrImageInput(bitmap)
            Dim reader = New QrReader()
            Dim results = reader.Read(imageInput)

            Dim decoded = results.Select(Function(r) New With {Key .Value = r.Value, Key .Url = r.Url}).ToList()
            Return Ok(decoded)
        End Using
    End Function
End Class

El método AnyBitmap.FromStream() acepta cualquier flujo legible, por lo que la misma ruta de código funciona para archivos cargados a través de un formulario, imágenes recuperadas del almacenamiento de blobs o fotogramas extraídos de un canal de vídeo. El controlador no escribe ningún archivo temporal en el disco, lo cual es importante para implementaciones en contenedores donde el sistema de archivos puede ser de solo lectura.

Para escenarios de alto rendimiento, instancie QrReader una vez por ciclo de vida de la aplicación como un singleton, ya que el coste de carga del modelo de ML se paga en la primera construcción. Las llamadas posteriores a Read() en la misma instancia son seguras para subprocesos y comparten el modelo cargado.

¿Cómo se generan códigos QR en una aplicación .NET MAUI?

El tutorial sobre códigos QR de .NET MAUI muestra la generación multiplataforma completa en iOS, Android, macOS y Windows. IronQR utiliza el backend de renderizado SkiaSharp cuando se ejecuta en plataformas que no sean Windows, lo que proporciona un resultado coherente en todos los destinos MAUI.

using IronQr;
using IronSoftware.Drawing;

// Generate QR and convert to a byte array for display in MAUI
QrCode qr = QrWriter.Write("https://ironsoftware.com/csharp/qr/");
AnyBitmap bitmap = qr.Save();
byte[] imageBytes = bitmap.ExportBytes();

// Bind imageBytes to an <Image Source> in your MAUI page

using IronQr;
using IronSoftware.Drawing;

// Generate QR and convert to a byte array for display in MAUI
QrCode qr = QrWriter.Write("https://ironsoftware.com/csharp/qr/");
AnyBitmap bitmap = qr.Save();
byte[] imageBytes = bitmap.ExportBytes();

// Bind imageBytes to an <Image Source> in your MAUI page

Imports IronQr
Imports IronSoftware.Drawing

' Generate QR and convert to a byte array for display in MAUI
Dim qr As QrCode = QrWriter.Write("https://ironsoftware.com/csharp/qr/")
Dim bitmap As AnyBitmap = qr.Save()
Dim imageBytes As Byte() = bitmap.ExportBytes()

' Bind imageBytes to an <Image Source> in your MAUI page

En dispositivos móviles, ExportBytes() devuelve una matriz de bytes PNG que se puede introducir directamente en un StreamImageSource o escribir en un ImageButton. El andamio MAUI no requiere rutas de código específicas para cada plataforma: la misma lógica de generación se ejecuta de forma idéntica en los cuatro destinos de MAUI.

Para los proyectos VB.NET, la interfaz de la API es idéntica; solo difiere la sintaxis. La biblioteca se distribuye en un único paquete NuGet sin necesidad de un ensamblado VB.NET independiente.

¿Cuales son tus próximos pasos?

IronQR cubre el ciclo de vida completo de los códigos QR en .NET, desde la generación básica y la codificación estructurada de la carga útil hasta la lectura, basada en aprendizaje automático, de códigos dañados o con marca. Para empresas que operan en España, IronQR es la herramienta que permite cumplir con las obligaciones del sistema VeriFactu de la AEAT (QR en cada factura con leyenda VERI*FACTU), del TicketBAI en el País Vasco (Bizkaia, Gipuzkoa, Araba), y de la futura obligación B2B de Crea y Crece. La biblioteca gestiona la codificación de kanji, la configuración de la corrección de errores y la salida de imágenes multiplataforma, lo que te permite centrarte en la lógica específica de tu aplicación.

Para poner en práctica lo que has aprendido:

• Consulte el tutorial del lector de códigos QR en C# para obtener información más detallada sobre la API de lectura y el procesamiento de resultados.
• Siga el tutorial de la aplicación generadora de códigos QR en C# para obtener una guía completa del proyecto.
• Echa un vistazo a los ejemplos de código para ver más patrones de generación y lectura.
• Adquiera una licencia de IronQR para desbloquear todas las funciones para la implementación en producción, o amplíe la prueba gratuita si necesita más tiempo de evaluación.