Formattatori personalizzati nell'API Web ASP.NET Core

ASP.NET Core MVC supporta lo scambio di dati nelle API Web usando formattatori di input e output. I formattatori di input vengono usati da Model Binding. I formattatori di output vengono usati per formattare le risposte.

Il framework fornisce formattatori di input e output predefiniti per JSON e XML. Fornisce un formattatore di output predefinito per il testo normale, ma non fornisce un formattatore di input per il testo normale.

In questo articolo viene illustrato come aggiungere supporto per altri formati creando formattatori personalizzati. Per un esempio di formattatore di input di testo normale personalizzato, vedere TextPlainInputFormatter su GitHub.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Quando usare un formattatore personalizzato

Usare un formattatore personalizzato per aggiungere il supporto per un tipo di contenuto non gestito dai formattatori predefiniti.

Panoramica di come creare un formattatore personalizzato

Per creare un formattatore personalizzato:

  • Per serializzare i dati inviati al client, creare una classe formattatore di output.
  • Per deserializzare i dati ricevuti dal client, creare una classe formattatore di input.
  • Aggiungere istanze di classi formattatore alle raccolte InputFormatters e OutputFormatters in MvcOptions.

Creare un formattatore personalizzato

Per creare un formattatore:

Il codice seguente illustra la VcardOutputFormatter classe dell'esempio:

public class VcardOutputFormatter : TextOutputFormatter
{
    public VcardOutputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }

    protected override bool CanWriteType(Type? type)
        => typeof(Contact).IsAssignableFrom(type)
            || typeof(IEnumerable<Contact>).IsAssignableFrom(type);

    public override async Task WriteResponseBodyAsync(
        OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        var httpContext = context.HttpContext;
        var serviceProvider = httpContext.RequestServices;

        var logger = serviceProvider.GetRequiredService<ILogger<VcardOutputFormatter>>();
        var buffer = new StringBuilder();

        if (context.Object is IEnumerable<Contact> contacts)
        {
            foreach (var contact in contacts)
            {
                FormatVcard(buffer, contact, logger);
            }
        }
        else
        {
            FormatVcard(buffer, (Contact)context.Object!, logger);
        }

        await httpContext.Response.WriteAsync(buffer.ToString(), selectedEncoding);
    }

    private static void FormatVcard(
        StringBuilder buffer, Contact contact, ILogger logger)
    {
        buffer.AppendLine("BEGIN:VCARD");
        buffer.AppendLine("VERSION:2.1");
        buffer.AppendLine($"N:{contact.LastName};{contact.FirstName}");
        buffer.AppendLine($"FN:{contact.FirstName} {contact.LastName}");
        buffer.AppendLine($"UID:{contact.Id}");
        buffer.AppendLine("END:VCARD");

        logger.LogInformation("Writing {FirstName} {LastName}",
            contact.FirstName, contact.LastName);
    }
}

Deriva dalla classe di base appropriata

Per i tipi di supporti di testo (ad esempio, vCard), derivare dalla classe base TextInputFormatter o TextOutputFormatter:

public class VcardOutputFormatter : TextOutputFormatter

Per i tipi binari, derivare dalla classe base InputFormatter o OutputFormatter.

Specificare i tipi di contenuto multimediale e le codifiche supportate

Nel costruttore specificare i tipi di contenuto supportati e le codifiche supportate aggiungendo alle raccolte SupportedMediaTypes e SupportedEncodings:

public VcardOutputFormatter()
{
    SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

    SupportedEncodings.Add(Encoding.UTF8);
    SupportedEncodings.Add(Encoding.Unicode);
}

Una classe formattatore non può usare l'inserimento del costruttore per le relative dipendenze. Ad esempio, ILogger<VcardOutputFormatter> non può essere aggiunto come parametro al costruttore. Per accedere ai servizi, utilizzare l'oggetto contesto passato ai metodi . Un esempio di codice in questo articolo e l'esempio illustrano come eseguire questa operazione.

Eseguire l'override di CanReadType e CanWriteType

Specificare il tipo in cui deserializzare o da cui serializzare eseguendo l'override dei metodi CanReadType o CanWriteType. Ad esempio, per creare testo vCard da un tipo Contact e viceversa:

protected override bool CanWriteType(Type? type)
    => typeof(Contact).IsAssignableFrom(type)
        || typeof(IEnumerable<Contact>).IsAssignableFrom(type);

Il metodo CanWriteResult

In alcuni scenari, CanWriteResult deve essere sovrascritto anziché CanWriteType. Usare CanWriteResult se vengono soddisfatte le condizioni seguenti:

  • Il metodo action restituisce una classe modello.
  • Esistono classi derivate che potrebbero essere restituite in fase di esecuzione.
  • La classe derivata restituita dall'azione deve essere nota in fase di esecuzione.

Si supponga, ad esempio, il seguente metodo action:

  • La firma restituisce un tipo Person.
  • Può restituire un tipo Student o Instructor che deriva da Person.

Affinché il formattatore gestisca solo gli oggetti Student, controllare il tipo di Object nell'oggetto di contesto fornito al metodo CanWriteResult. Quando il metodo di azione restituisce IActionResult:

  • Non è necessario usare CanWriteResult.
  • Il CanWriteType metodo riceve il tipo di runtime.

Eseguire l'override dei metodi ReadRequestBodyAsync e WriteResponseBodyAsync

La deserializzazione o la serializzazione viene eseguita in ReadRequestBodyAsync o WriteResponseBodyAsync. Nell'esempio seguente viene illustrato come ottenere servizi dal contenitore di dependency injection. I servizi non possono essere ottenuti dai parametri del costruttore:

public override async Task WriteResponseBodyAsync(
    OutputFormatterWriteContext context, Encoding selectedEncoding)
{
    var httpContext = context.HttpContext;
    var serviceProvider = httpContext.RequestServices;

    var logger = serviceProvider.GetRequiredService<ILogger<VcardOutputFormatter>>();
    var buffer = new StringBuilder();

    if (context.Object is IEnumerable<Contact> contacts)
    {
        foreach (var contact in contacts)
        {
            FormatVcard(buffer, contact, logger);
        }
    }
    else
    {
        FormatVcard(buffer, (Contact)context.Object!, logger);
    }

    await httpContext.Response.WriteAsync(buffer.ToString(), selectedEncoding);
}

private static void FormatVcard(
    StringBuilder buffer, Contact contact, ILogger logger)
{
    buffer.AppendLine("BEGIN:VCARD");
    buffer.AppendLine("VERSION:2.1");
    buffer.AppendLine($"N:{contact.LastName};{contact.FirstName}");
    buffer.AppendLine($"FN:{contact.FirstName} {contact.LastName}");
    buffer.AppendLine($"UID:{contact.Id}");
    buffer.AppendLine("END:VCARD");

    logger.LogInformation("Writing {FirstName} {LastName}",
        contact.FirstName, contact.LastName);
}

Configurare MVC per l'uso di un formattatore personalizzato

Per usare un formattatore personalizzato, aggiungere un'istanza della classe del formattatore alla raccolta MvcOptions.InputFormatters o MvcOptions.OutputFormatters:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
{
    options.InputFormatters.Insert(0, new VcardInputFormatter());
    options.OutputFormatters.Insert(0, new VcardOutputFormatter());
});

I formattatori vengono valutati nell'ordine in cui vengono inseriti, dove il primo ha la precedenza.

La classe completa VcardInputFormatter

Il codice seguente illustra la VcardInputFormatter classe dell'esempio:

public class VcardInputFormatter : TextInputFormatter
{
    public VcardInputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }

    protected override bool CanReadType(Type type)
        => type == typeof(Contact);

    public override async Task<InputFormatterResult> ReadRequestBodyAsync(
        InputFormatterContext context, Encoding effectiveEncoding)
    {
        var httpContext = context.HttpContext;
        var serviceProvider = httpContext.RequestServices;

        var logger = serviceProvider.GetRequiredService<ILogger<VcardInputFormatter>>();

        using var reader = new StreamReader(httpContext.Request.Body, effectiveEncoding);
        string? nameLine = null;

        try
        {
            await ReadLineAsync("BEGIN:VCARD", reader, context, logger);
            await ReadLineAsync("VERSION:", reader, context, logger);

            nameLine = await ReadLineAsync("N:", reader, context, logger);

            var split = nameLine.Split(";".ToCharArray());
            var contact = new Contact(FirstName: split[1], LastName: split[0].Substring(2));

            await ReadLineAsync("FN:", reader, context, logger);
            await ReadLineAsync("END:VCARD", reader, context, logger);

            logger.LogInformation("nameLine = {nameLine}", nameLine);

            return await InputFormatterResult.SuccessAsync(contact);
        }
        catch
        {
            logger.LogError("Read failed: nameLine = {nameLine}", nameLine);
            return await InputFormatterResult.FailureAsync();
        }
    }

    private static async Task<string> ReadLineAsync(
        string expectedText, StreamReader reader, InputFormatterContext context,
        ILogger logger)
    {
        var line = await reader.ReadLineAsync();

        if (line is null || !line.StartsWith(expectedText))
        {
            var errorMessage = $"Looked for '{expectedText}' and got '{line}'";

            context.ModelState.TryAddModelError(context.ModelName, errorMessage);
            logger.LogError(errorMessage);

            throw new Exception(errorMessage);
        }

        return line;
    }
}

Prova l'app

Eseguire l'app di esempio per questo articolo, che implementa formattatori di input e output vCard di base. L'app legge e scrive vCard in modo simile al formato seguente:

BEGIN:VCARD
VERSION:2.1
N:Davolio;Nancy
FN:Nancy Davolio
END:VCARD

Per visualizzare l'output vCard, eseguire l'app e inviare una richiesta Get con l'intestazione text/vcard Accept a https://localhost:<port>/api/contacts.

Per aggiungere una vCard alla raccolta in memoria dei contatti:

  • Inviare una Post richiesta a /api/contacts con uno strumento come http-repl.
  • Impostare l'intestazione Content-Type su text/vcard.
  • Impostare vCard il testo nel corpo, formattato come nell'esempio precedente.

Risorse aggiuntive

ASP.NET Core MVC supporta lo scambio di dati nelle API Web usando formattatori di input e output. I formattatori di input vengono usati da Model Binding. I formattatori di output vengono usati per formattare le risposte.

Il framework fornisce formattatori di input e output predefiniti per JSON e XML. Fornisce un formattatore di output predefinito per il testo normale, ma non fornisce un formattatore di input per il testo normale.

In questo articolo viene illustrato come aggiungere supporto per altri formati creando formattatori personalizzati. Per un esempio di formattatore di input di testo normale personalizzato, vedere TextPlainInputFormatter su GitHub.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Quando usare un formattatore personalizzato

Usare un formattatore personalizzato per aggiungere il supporto per un tipo di contenuto non gestito dai formattatori predefiniti.

Panoramica di come creare un formattatore personalizzato

Per creare un formattatore personalizzato:

  • Per serializzare i dati inviati al client, creare una classe formattatore di output.
  • Per deserializzare i dati ricevuti dal client, creare una classe formattatore di input.
  • Aggiungere istanze di classi formattatore alle raccolte InputFormatters e OutputFormatters in MvcOptions.

Creare un formattatore personalizzato

Per creare un formattatore:

Il codice seguente illustra la VcardOutputFormatter classe dell'esempio:

public class VcardOutputFormatter : TextOutputFormatter
{
    public VcardOutputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }

    protected override bool CanWriteType(Type type)
    {
        return typeof(Contact).IsAssignableFrom(type) ||
            typeof(IEnumerable<Contact>).IsAssignableFrom(type);
    }

    public override async Task WriteResponseBodyAsync(
        OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        var httpContext = context.HttpContext;
        var serviceProvider = httpContext.RequestServices;

        var logger = serviceProvider.GetRequiredService<ILogger<VcardOutputFormatter>>();
        var buffer = new StringBuilder();

        if (context.Object is IEnumerable<Contact> contacts)
        {
            foreach (var contact in contacts)
            {
                FormatVcard(buffer, contact, logger);
            }
        }
        else
        {
            FormatVcard(buffer, (Contact)context.Object, logger);
        }

        await httpContext.Response.WriteAsync(buffer.ToString(), selectedEncoding);
    }

    private static void FormatVcard(
        StringBuilder buffer, Contact contact, ILogger logger)
    {
        buffer.AppendLine("BEGIN:VCARD");
        buffer.AppendLine("VERSION:2.1");
        buffer.AppendLine($"N:{contact.LastName};{contact.FirstName}");
        buffer.AppendLine($"FN:{contact.FirstName} {contact.LastName}");
        buffer.AppendLine($"UID:{contact.Id}");
        buffer.AppendLine("END:VCARD");

        logger.LogInformation("Writing {FirstName} {LastName}",
            contact.FirstName, contact.LastName);
    }
}

Deriva dalla classe di base appropriata

Per i tipi di supporti di testo (ad esempio, vCard), derivare dalla classe base TextInputFormatter o TextOutputFormatter:

public class VcardOutputFormatter : TextOutputFormatter

Per i tipi binari, derivare dalla classe base InputFormatter o OutputFormatter.

Specificare i tipi di contenuto multimediale e le codifiche supportate

Nel costruttore specificare i tipi di contenuto supportati e le codifiche supportate aggiungendo alle raccolte SupportedMediaTypes e SupportedEncodings:

public VcardOutputFormatter()
{
    SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

    SupportedEncodings.Add(Encoding.UTF8);
    SupportedEncodings.Add(Encoding.Unicode);
}

Una classe formattatore non può usare l'inserimento del costruttore per le relative dipendenze. Ad esempio, ILogger<VcardOutputFormatter> non può essere aggiunto come parametro al costruttore. Per accedere ai servizi, utilizzare l'oggetto contesto passato ai metodi . Un esempio di codice in questo articolo e l'esempio illustrano come eseguire questa operazione.

Eseguire l'override di CanReadType e CanWriteType

Specificare il tipo in cui deserializzare o da cui serializzare eseguendo l'override dei metodi CanReadType o CanWriteType. Ad esempio, per creare testo vCard da un tipo Contact e viceversa:

protected override bool CanWriteType(Type type)
{
    return typeof(Contact).IsAssignableFrom(type) ||
        typeof(IEnumerable<Contact>).IsAssignableFrom(type);
}

Il metodo CanWriteResult

In alcuni scenari, CanWriteResult deve essere sovrascritto anziché CanWriteType. Usare CanWriteResult se vengono soddisfatte le condizioni seguenti:

  • Il metodo action restituisce una classe modello.
  • Esistono classi derivate che potrebbero essere restituite in fase di esecuzione.
  • La classe derivata restituita dall'azione deve essere nota in fase di esecuzione.

Si supponga, ad esempio, il seguente metodo action:

  • La firma restituisce un tipo Person.
  • Può restituire un tipo Student o Instructor che deriva da Person.

Affinché il formattatore gestisca solo gli oggetti Student, controllare il tipo di Object nell'oggetto di contesto fornito al metodo CanWriteResult. Quando il metodo di azione restituisce IActionResult:

  • Non è necessario usare CanWriteResult.
  • Il CanWriteType metodo riceve il tipo di runtime.

Eseguire l'override dei metodi ReadRequestBodyAsync e WriteResponseBodyAsync

La deserializzazione o la serializzazione viene eseguita in ReadRequestBodyAsync o WriteResponseBodyAsync. Nell'esempio seguente viene illustrato come ottenere servizi dal contenitore di dependency injection. I servizi non possono essere ottenuti dai parametri del costruttore:

public override async Task WriteResponseBodyAsync(
    OutputFormatterWriteContext context, Encoding selectedEncoding)
{
    var httpContext = context.HttpContext;
    var serviceProvider = httpContext.RequestServices;

    var logger = serviceProvider.GetRequiredService<ILogger<VcardOutputFormatter>>();
    var buffer = new StringBuilder();

    if (context.Object is IEnumerable<Contact> contacts)
    {
        foreach (var contact in contacts)
        {
            FormatVcard(buffer, contact, logger);
        }
    }
    else
    {
        FormatVcard(buffer, (Contact)context.Object, logger);
    }

    await httpContext.Response.WriteAsync(buffer.ToString(), selectedEncoding);
}

private static void FormatVcard(
    StringBuilder buffer, Contact contact, ILogger logger)
{
    buffer.AppendLine("BEGIN:VCARD");
    buffer.AppendLine("VERSION:2.1");
    buffer.AppendLine($"N:{contact.LastName};{contact.FirstName}");
    buffer.AppendLine($"FN:{contact.FirstName} {contact.LastName}");
    buffer.AppendLine($"UID:{contact.Id}");
    buffer.AppendLine("END:VCARD");

    logger.LogInformation("Writing {FirstName} {LastName}",
        contact.FirstName, contact.LastName);
}

Configurare MVC per l'uso di un formattatore personalizzato

Per usare un formattatore personalizzato, aggiungere un'istanza della classe del formattatore alla raccolta MvcOptions.InputFormatters o MvcOptions.OutputFormatters:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        options.InputFormatters.Insert(0, new VcardInputFormatter());
        options.OutputFormatters.Insert(0, new VcardOutputFormatter());
    });
}

I formattatori vengono valutati nell'ordine d'inserimento. Il primo ha la precedenza.

La classe completa VcardInputFormatter

Il codice seguente illustra la VcardInputFormatter classe dell'esempio:

public class VcardInputFormatter : TextInputFormatter
{
    public VcardInputFormatter()
    {
        SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/vcard"));

        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }

    protected override bool CanReadType(Type type)
    {
        return type == typeof(Contact);
    }

    public override async Task<InputFormatterResult> ReadRequestBodyAsync(
        InputFormatterContext context, Encoding effectiveEncoding)
    {
        var httpContext = context.HttpContext;
        var serviceProvider = httpContext.RequestServices;

        var logger = serviceProvider.GetRequiredService<ILogger<VcardInputFormatter>>();

        using var reader = new StreamReader(httpContext.Request.Body, effectiveEncoding);
        string nameLine = null;

        try
        {
            await ReadLineAsync("BEGIN:VCARD", reader, context, logger);
            await ReadLineAsync("VERSION:", reader, context, logger);

            nameLine = await ReadLineAsync("N:", reader, context, logger);

            var split = nameLine.Split(";".ToCharArray());
            var contact = new Contact
            {
                LastName = split[0].Substring(2),
                FirstName = split[1]
            };

            await ReadLineAsync("FN:", reader, context, logger);
            await ReadLineAsync("END:VCARD", reader, context, logger);

            logger.LogInformation("nameLine = {nameLine}", nameLine);

            return await InputFormatterResult.SuccessAsync(contact);
        }
        catch
        {
            logger.LogError("Read failed: nameLine = {nameLine}", nameLine);
            return await InputFormatterResult.FailureAsync();
        }
    }

    private static async Task<string> ReadLineAsync(
        string expectedText, StreamReader reader, InputFormatterContext context,
        ILogger logger)
    {
        var line = await reader.ReadLineAsync();

        if (!line.StartsWith(expectedText))
        {
            var errorMessage = $"Looked for '{expectedText}' and got '{line}'";

            context.ModelState.TryAddModelError(context.ModelName, errorMessage);
            logger.LogError(errorMessage);

            throw new Exception(errorMessage);
        }

        return line;
    }
}

Prova l'app

Eseguire l'app di esempio per questo articolo, che implementa formattatori di input e output vCard di base. L'app legge e scrive vCard in modo simile al formato seguente:

BEGIN:VCARD
VERSION:2.1
N:Davolio;Nancy
FN:Nancy Davolio
END:VCARD

Per visualizzare l'output vCard, eseguire l'app e inviare una richiesta Get con l'intestazione text/vcard Accept a https://localhost:5001/api/contacts.

Per aggiungere una vCard alla raccolta in memoria dei contatti:

  • Inviare una Post richiesta a /api/contacts con uno strumento come curl.
  • Impostare l'intestazione Content-Type su text/vcard.
  • Impostare vCard il testo nel corpo, formattato come nell'esempio precedente.

Risorse aggiuntive