En la era digital de hoy, el manejo eficiente de la imagen es crucial para las aplicaciones web y APIs. Uno de los aspectos clave de gestión de imágenes es la compresión, que ayuda a reducir los tamaños de archivos sin comprometer significativamente la calidad. Esta guía te va a través de construir una API de comprensión de imagen dinámica utilizando Aspose.Imaging para .NET. Al final, tendrás una funcional ASP.NET Core Web API que acepta las imágenes y devuelve la producción comprimida según los parámetros de consulta (formato, calidad, resignación, y más).

Aspose.Imaging es una potente biblioteca para trabajar con imágenes en .NET. apoya muchos formatos y proporciona funciones de manipulación robustas, incluyendo los flujos de trabajo perdidos (JPEG) y sin pérdidas (PNG).

Lo que construirás

  • El punto final: POST /api/images/compress?format=jpeg&quality=75&maxWidth=1280&maxHeight=1280
  • Inputs: archivo de múltiples partes (imagen), parámetros de consulta opcionales para formato/calidad/resigüedad
  • Outputs: flujo de imagen comprimido con correcto Content-Type y cabezas de caching
  • Seguridad: validación de tipo de contenido, límites de tamaño y codificación guardada/encode

Prerequisitos

  • .NET 8 (o .NET 6+)
  • Proyecto ASP.NET Core Web API
  • El NuGet: Aspose.Imaging
  • Opcional: Iniciación de licencia en la startup de la app (si está utilizando un edificio licenciado)

Estructura del proyecto (mínimo)

/Controllers
  ImageController.cs
/Services
  ImageCompressionService.cs
/Models
  CompressionRequest.cs
Program.cs
appsettings.json

Ejemplo completo (Service + Controller)

Reemplaza los espacios de nombre del lugar con el nombre de espacio de su proyecto.

/Models/CompressionRequest.cs

namespace ImageApi.Models;

public sealed class CompressionRequest
{
    // "jpeg" or "png"
    public string Format { get; init; } = "jpeg";

    // 1..100 (applies to JPEG only; PNG is lossless)
    public int? Quality { get; init; } = 80;

    // Optional resize bounds; image is resized preserving aspect ratio if either is provided.
    public int? MaxWidth { get; init; }
    public int? MaxHeight { get; init; }

    // If true, strip metadata (EXIF, IPTC) where applicable to reduce size further.
    public bool StripMetadata { get; init; } = true;

    // Guardrails
    public void Validate()
    {
        var fmt = Format?.ToLowerInvariant();
        if (fmt is not "jpeg" and not "png")
            throw new ArgumentException("Unsupported format. Use 'jpeg' or 'png'.");

        if (Quality is { } q && (q < 1 || q > 100))
            throw new ArgumentException("Quality must be between 1 and 100.");

        if (MaxWidth is { } w && w <= 0) throw new ArgumentException("MaxWidth must be positive.");
        if (MaxHeight is { } h && h <= 0) throw new ArgumentException("MaxHeight must be positive.");
    }
}

/Services/ImageCompressionService.cs

using Aspose.Imaging;
using Aspose.Imaging.ImageOptions;
using ImageApi.Models;

namespace ImageApi.Services;

public interface IImageCompressionService
{
    Task<(MemoryStream output, string contentType, string fileExt)> CompressAsync(
        Stream input, CompressionRequest req, CancellationToken ct = default);
}

public sealed class ImageCompressionService : IImageCompressionService
{
    private readonly ILogger<ImageCompressionService> _logger;

    public ImageCompressionService(ILogger<ImageCompressionService> logger)
    {
        _logger = logger;
    }

    public async Task<(MemoryStream output, string contentType, string fileExt)> CompressAsync(
        Stream input, CompressionRequest req, CancellationToken ct = default)
    {
        req.Validate();

        // Defensive copy to a seekable stream
        var inbound = new MemoryStream();
        await input.CopyToAsync(inbound, ct).ConfigureAwait(false);
        inbound.Position = 0;

        // Load image via Aspose.Imaging
        using var image = Image.Load(inbound);

        // Optional: strip metadata (where applicable)
        if (req.StripMetadata)
        {
            TryStripMetadata(image);
        }

        // Optional resize (preserve aspect ratio)
        if (req.MaxWidth.HasValue || req.MaxHeight.HasValue)
        {
            ResizeInPlace(image, req.MaxWidth, req.MaxHeight);
        }

        // Choose encoder and options
        string fmt = req.Format.ToLowerInvariant();
        var (options, contentType, ext) = BuildOptions(fmt, req.Quality);

        // Save to output
        var output = new MemoryStream();
        image.Save(output, options);
        output.Position = 0;

        _logger.LogInformation("Compressed image to {Bytes} bytes as {Ext}", output.Length, ext);
        return (output, contentType, ext);
    }

    private static void ResizeInPlace(Image image, int? maxW, int? maxH)
    {
        var w = image.Width;
        var h = image.Height;

        double scaleW = maxW.HasValue ? (double)maxW.Value / w : 1.0;
        double scaleH = maxH.HasValue ? (double)maxH.Value / h : 1.0;
        double scale = Math.Min(scaleW, scaleH);

        if (scale < 1.0)
        {
            int newW = Math.Max(1, (int)Math.Round(w * scale));
            int newH = Math.Max(1, (int)Math.Round(h * scale));
            image.Resize(newW, newH);
        }
    }

    private static (ImageOptionsBase options, string contentType, string ext) BuildOptions(string fmt, int? quality)
    {
        switch (fmt)
        {
            case "jpeg":
            {
                var q = quality ?? 80;
                var jpeg = new JpegOptions { Quality = q };
                return (jpeg, "image/jpeg", "jpg");
            }
            case "png":
            {
                // PNG is lossless; using defaults ensures broad compatibility.
                // Many PNG tunables exist, but defaults are safe and effective.
                var png = new PngOptions();
                return (png, "image/png", "png");
            }
            default:
                throw new ArgumentOutOfRangeException(nameof(fmt), "Unsupported format.");
        }
    }

    private static void TryStripMetadata(Image image)
    {
        try
        {
            // Not every format exposes EXIF/IPTC the same way; a best-effort clear:
            if (image is RasterImage raster)
            {
                raster.RemoveAllFonts();
                raster.SetPropertyItems(Array.Empty<PropertyItem>());
            }
        }
        catch
        {
            // Non-fatal; ignore if format doesn't support these operations
        }
    }
}

Notes

  • JpegOptions.Quality (1-100) controla la compresión de pérdida.
  • Los defectos de PNG son generalmente buenos para una primera versión; si necesitas pNG extra pequeños, puedes agregar tuning avanzado más tarde.
  • TryStripMetadata es un enfoque de mejor esfuerzo; los APIs de metadatos varían según el formato de fuente.

/Controllers/ImageController.cs

using ImageApi.Models;
using ImageApi.Services;
using Microsoft.AspNetCore.Mvc;

namespace ImageApi.Controllers;

[ApiController]
[Route("api/images")]
public sealed class ImageController : ControllerBase
{
    private static readonly HashSet<string> AllowedContentTypes = new(StringComparer.OrdinalIgnoreCase)
    {
        "image/jpeg", "image/png", "image/gif", "image/webp", "image/bmp", "image/tiff"
    };

    private readonly IImageCompressionService _svc;
    private readonly ILogger<ImageController> _logger;

    public ImageController(IImageCompressionService svc, ILogger<ImageController> logger)
    {
        _svc = svc;
        _logger = logger;
    }

    // POST /api/images/compress?format=jpeg&quality=75&maxWidth=1280&maxHeight=1280
    [HttpPost("compress")]
    [RequestSizeLimit(25_000_000)] // 25 MB cap; adjust to your needs
    public async Task<IActionResult> Compress(
        [FromQuery] string? format,
        [FromQuery] int? quality,
        [FromQuery] int? maxWidth,
        [FromQuery] int? maxHeight,
        [FromQuery] bool stripMetadata = true,
        IFormFile? file = null,
        CancellationToken ct = default)
    {
        if (file is null || file.Length == 0)
            return BadRequest("No file uploaded.");

        if (!AllowedContentTypes.Contains(file.ContentType))
            return BadRequest("Unsupported content type. Upload a common raster image (JPEG, PNG, GIF, WebP, BMP, TIFF).");

        var req = new CompressionRequest
        {
            Format = string.IsNullOrWhiteSpace(format) ? "jpeg" : format!,
            Quality = quality,
            MaxWidth = maxWidth,
            MaxHeight = maxHeight,
            StripMetadata = stripMetadata
        };

        await using var input = file.OpenReadStream();
        var (output, contentType, ext) = await _svc.CompressAsync(input, req, ct);

        // Strong caching for immutable responses (tune for your app/CDN)
        Response.Headers.CacheControl = "public,max-age=31536000,immutable";

        return File(output, contentType, fileDownloadName: BuildDownloadName(file.FileName, ext));
    }

    private static string BuildDownloadName(string originalName, string newExt)
    {
        var baseName = Path.GetFileNameWithoutExtension(originalName);
        return $"{baseName}-compressed.{newExt}";
    }
}

Program.cs (Registro + licencia opcional)

using Aspose.Imaging;
using ImageApi.Services;

var builder = WebApplication.CreateBuilder(args);

// Optional: initialize Aspose license from a file or stream if you have one
// var license = new Aspose.Imaging.License();
// license.SetLicense("Aspose.Total.lic");

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddSingleton<IImageCompressionService, ImageCompressionService>();

var app = builder.Build();

app.UseRouting();
app.UseAuthorization();
app.MapControllers();

// Enable for local testing
app.UseSwagger();
app.UseSwaggerUI();

app.Run();

Guía paso a paso

Paso 1: Configurar el proyecto

Crea un proyecto ASP.NET Core Web API. Aspose.Imaging NuGet paquete. crear el Models, Services, y Controllers Los archivos como se muestra anteriormente.

Paso 2: Configure Aspose.Imaging (licencia opcional)

Si usted tiene una licencia, iniciarla en la startup (ver Program.csEsto evita las puntuaciones de evaluación y garantiza la plena funcionalidad.

Paso 3: Implementar el servicio de compresión

El ImageCompressionService:

  • Cargar imágenes a través de Image.Load(Stream)
  • Opcionalmente cortar metadatos
  • Recupera opcionalmente con el ratio de aspecto conservado
  • ahorrar a JPEG o PNG con opciones adecuadas para el formato

Paso 4: Crea el controlador de API

ImageController Exposiciones POST /api/images/compress Tomar un archivo y cuestionar los parámetros:

  • format: jpeg o png (defaultamente jpeg)
  • quality1 a 100 (sólo JPEG; estándar 80)
  • maxWidth/maxHeightLos límites para la disminución
  • stripMetadataEl default true Para una producción menor

Paso 5: Testar el API

Utilice cualquier cliente HTTP para enviar un multipart/form-data solicitud con un solo campo de archivo llamado file, más parámetros de consulta opcionales. verifique:

  • Response Content-Type Formato de juegos
  • El tamaño de los archivos devueltos se reduce
  • Recuperar las obras como se esperaba

Opciones de diseño y mejores prácticas

  • Segundaciones de formato: JPEG utiliza QualityPNG permanece sin pérdidas para una producción previsible.
  • Downscale antes de codificar: Recodificación reduce los píxeles primero (el mayor tamaño ganan), luego codifica los bajetas más adelante.
  • Sanitiza las entradas: Tipo de contenido guardado, tamaño de archivo, límites de consulta.
  • Streaming: Evite leer todo el archivo en la memoria repetidamente; mantenga los flujos cortos de vida y buscables.
  • Caching: Marca las respuestas como inmutables si derive el nombre/contenido de las entradas deterministas; de lo contrario, tune los titulares de cache a su caso de uso.
  • Seguridad: Valida el tipo de contenido y rechaza los pagos sospechosos.
  • Observabilidad: Los tamaños de registro antes/después y los parámetros utilizados; esto te ayuda a tonar los defectos.
  • Trotling: Si expuesto públicamente, límite de tasa o requiere auth para prevenir el abuso.

Extensiones comunes (drop-in más tarde)

  • Codadores WebP/AVIF para imágenes aún más pequeñas (añadir nuevas opciones/contentTypeExtension de archivo en BuildOptions).).
  • PNG tuning (nivel de filtración/compresión) si necesita activos extra pequeños sin pérdida.
  • ** Preset perfiles** como thumbnail, preview, hires Descargar los parámetros conocidos.
  • ** Etiquetas** o hashing de contenido para servir las respuestas idénticas del cache.
  • Async batch final para comprimir varios archivos a la vez.

Troubleshooting

  • Muchos ingresos: Aumentar RequestSizeLimit o flujo al almacenamiento temp.
  • Colores verdes: El espacio de color garantizado se gestiona por defectos; los casos avanzados pueden necesitar un tipo de colores explícito.
  • Ninguna reducción de tamaño (PNG): PNG es sin pérdidas; permite la resignación o la transición a JPEG para ahorros de byte más fuertes.

Resumen

Ahora tienes una API de compresión de imagen dinámica preparada para la producción utilizando Aspose.Imaging. El controlador mantiene las cargas y los parámetros; el servicio aplica la composición segura, informada de formato y la resignación opcional, luego vuelve a fluir una respuesta correctamente tipada con las cabezas de cache. Desde aquí, puedes agregar más formatos, preceptos y estrategias del caching para adaptarte a tu web stack.

More in this category