Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ServiceComposer/ServiceComposer.AspNetCore/llms.txt

Use this file to discover all available pages before exploring further.

ServiceComposer serializes composed responses using System.Text.Json and exposes three complementary mechanisms for controlling how that output looks: a built-in casing convention (switchable per-request via an HTTP header), a default casing override at startup, fully custom JsonSerializerOptions per request, and the ability to delegate serialization entirely to ASP.NET Core’s output formatter pipeline. Each mechanism builds on the previous, so you can adopt as much or as little as your API contract requires.

​
Response casing

By default, ServiceComposer serializes responses using camel case — a C# property named SampleProperty appears in the JSON as sampleProperty. Consumers can request a different casing for a specific call by sending the custom Accept-Casing HTTP header:
Header valueCasing applied
casing/camelCamel case (default)
casing/pascalPascal case

​
Camel case serializer settings

When camel casing is active, ServiceComposer builds the following JsonSerializerOptions: 
var settings = new JsonSerializerOptions()
{
    // System.Text.Json requires both properties to be
    // set to properly format serialized responses
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    DictionaryKeyPolicy = JsonNamingPolicy.CamelCase
};

​
Pascal case serializer settings

When pascal casing is active, a plain JsonSerializerOptions instance is used (no naming policy, which corresponds to pascal/default .NET naming): 
var settings = new JsonSerializerOptions();

​
Setting a default casing at startup

Available starting with v1.8.0 If the majority of your clients expect pascal case, you can flip the default so that requests without an Accept-Casing header are serialized in pascal case. The Accept-Casing header is still respected when present. 
builder.Services.AddRouting();
builder.Services.AddViewModelComposition(options =>
{
    options.ResponseSerialization.DefaultResponseCasing = ResponseCasing.PascalCase;
});
ResponseCasing is an enum with two members:
MemberValue
CamelCase0 (default)
PascalCase1

​
Custom JSON serializer settings

Available starting with v1.8.0 For complete control over serialization — adding converters, changing number handling, enabling comments, etc. — supply a factory function via UseCustomJsonSerializerSettings. ServiceComposer calls your function for every response it needs to serialize, passing the current HttpRequest so you can adapt settings to the incoming request if needed. 
builder.Services.AddRouting();
builder.Services.AddViewModelComposition(options =>
{
    options.ResponseSerialization.UseCustomJsonSerializerSettings(_ =>
    {
        return new JsonSerializerOptions()
        {
            // customize options as needed
        };
    });
});
When you supply a custom settings factory you own the entire JsonSerializerOptions object. If you still want to honour the Accept-Casing header, you must inspect it in your factory and set PropertyNamingPolicy and DictionaryKeyPolicy accordingly.
UseCustomJsonSerializerSettings and DefaultResponseCasing are ignored when UseOutputFormatters is set to true. ServiceComposer logs a warning at startup if both are configured simultaneously.

​
Output formatters

Available starting with v1.9.0 Enabling output formatters delegates response serialization to the ASP.NET Core MVC formatter pipeline. This unlocks content negotiation, Newtonsoft Json.NET support, and any other formatter registered with MVC.
1

Enable output formatters

Set UseOutputFormatters to true in AddViewModelComposition:
builder.Services.AddViewModelComposition(options =>
{
    options.ResponseSerialization.UseOutputFormatters = true;
});
builder.Services.AddControllers();
2

Register MVC services

At least one of the following MVC service registrations must be present:
  • AddControllers()
  • AddControllersAndViews()
  • AddMvc()
  • AddRazorPages()

​
Using Newtonsoft Json.NET as the output formatter

Add the Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet package, then chain AddNewtonsoftJson(): 
builder.Services.AddViewModelComposition(options =>
{
    options.ResponseSerialization.UseOutputFormatters = true;
});
builder.Services.AddControllers()
    .AddNewtonsoftJson();

​
Choosing the right approach

Accept-Casing header

Let individual consumers choose camel or pascal casing per request. No configuration needed — works out of the box.

DefaultResponseCasing

Change the server-side default when most clients expect pascal case. Consumers can still override with the header.

UseCustomJsonSerializerSettings

Need custom converters, enum handling, or other JsonSerializerOptions tweaks? Supply a per-request factory function. Available since v1.8.0.

UseOutputFormatters

Need full MVC content negotiation or Newtonsoft Json.NET? Delegate serialization to the MVC formatter pipeline. Available since v1.9.0.

Build docs developers (and LLMs) love

Get started for freeTalk to us