Configuration

Complete reference for all JSON Serialization configuration options.

---

JsonSerializationOptions

Namespace: AspNetConventions.Configuration.Options
Accessed via: options.Json

Controls JSON serialization behaviour application-wide, covering both API response output and model serialization. The default underlying serializer is System.Text.Json.

ScanAssemblies

public void ScanAssemblies(params Assembly[] assemblies)

Scans the specified assemblies for all concrete, non-generic subclasses of JsonTypeConfigurationBase (which includes JsonTypeConfiguration<T> and JsonOpenGenericTypeConfiguration<T>) and registers their rules automatically.

Usage:

options.Json.ScanAssemblies(typeof(UserConfiguration).Assembly);

ConfigureAdapter

Use ConfigureAdapter<TAdapter, TOptions> to swap the active serializer adapter or to reach low-level settings of the current adapter that are not exposed through the standard options.Json.* API:

public void ConfigureAdapter<TAdapter, TOptions>(Action<TOptions>? configure = null)
    where TAdapter : IJsonSerializerAdapter

Configures a custom serializer adapter. The built-in default is SystemTextJsonAdapter.

Usage:

// Reach native System.Text.Json settings not covered by the standard API
options.Json.ConfigureAdapter<SystemTextJsonAdapter, JsonSerializerOptions>(serializerOptions =>
{
    serializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping;
    serializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
});

GetSerializerOptions

public object GetSerializerOptions()

Returns the underlying serializer options object from the configured adapter. Useful for directly inspecting the final serializer options at startup.

---

IJsonTypesConfigurationBuilder

Namespace: AspNetConventions.Serialization.Configuration
Accessed via: options.Json.ConfigureTypes = cfg => { ... }

Provides the fluent API for registering rules across multiple types.

All methods return IJsonTypesConfigurationBuilder for chaining:

options.Json.ConfigureTypes = cfg =>
{
    cfg
        .Type<User>(t => t.Property(x => x.Password).Ignore())
        .Type<Order>(t => t.Property(x => x.InternalRef).Ignore())
        .IgnorePropertyName("StatusCode")
        .IgnoreType<AuditTrail>();
};

---

IJsonTypeRuleBuilder<T>

Namespace: AspNetConventions.Serialization.Configuration

Provides property selection for a specific type T.

cfg.Type<User>(type =>
{
    type.Property(x => x.Id);          // selects User.Id
    type.Property(x => x.UserName);    // selects User.UserName
});

---

IJsonPropertyRuleBuilder

Namespace: AspNetConventions.Serialization.Configuration

Configures the selected property. All methods return IJsonPropertyRuleBuilder for chaining.

Chaining example:

type.Property(x => x.OrderId).Name("id").Order(0);

---

JsonTypeConfiguration<T>

Namespace: AspNetConventions.Serialization.Configuration

Abstract base class for class-based JSON configuration for a single closed type.

public abstract class JsonTypeConfiguration<T> : JsonTypeConfigurationBase
{
    public abstract void Configure(IJsonTypeRuleBuilder<T> rule);
}

Usage:

public class ProductConfiguration : JsonTypeConfiguration<Product>
{
    public override void Configure(IJsonTypeRuleBuilder<Product> rule)
    {
        rule.Property(x => x.CostPrice).Ignore();
        rule.Property(x => x.DisplayName).Name("name");
    }
}

Register via ScanAssemblies or inline:

// Via assembly scanning (recommended)
options.Json.ScanAssemblies(typeof(ProductConfiguration).Assembly);

// Inline — inside the ConfigureTypes delegate
options.Json.ConfigureTypes = cfg =>
{
    cfg.Type<Product>(type => new ProductConfiguration().Configure(type));
};

---

JsonOpenGenericTypeConfiguration<T>

Namespace: AspNetConventions.Serialization.Configuration

Abstract base class for class-based JSON configuration for open generic types. T must be a closed instantiation of the generic type used as a property-selection template.

public abstract class JsonOpenGenericTypeConfiguration<T> : JsonTypeConfigurationBase
{
    public abstract void Configure(IJsonTypeRuleBuilder<T> rule);
}

Usage:

// Rules are applied to MyApiResponse<string>, MyApiResponse<User>, MyApiResponse<anything>, etc.
public class MyApiResponseConfiguration : JsonOpenGenericTypeConfiguration<MyApiResponse<object>>
{
    public override void Configure(IJsonTypeRuleBuilder<MyApiResponse<object>> rule)
    {
        rule.Property(x => x.Data).Order(3);
        rule.Property(x => x.DebugInfo).Ignore();
    }
}

---

CasingStyle

Namespace: AspNetConventions.Core.Enums
Accessed via: options.Json.CaseStyle

---

NumberHandling

Namespace: AspNetConventions.Core.Enums.Json
Accessed via: options.Json.NumberHandling

---

IgnoreCondition

Namespace: AspNetConventions.Core.Enums.Json
Accessed via: options.Json.IgnoreCondition

This is the global default ignore condition that applies to all properties unless overridden by a more specific rule.

---

JsonSerializationHooks

Namespace: AspNetConventions.Core.Hooks
Accessed via: options.Json.Hooks

Examples:

// Suppress all properties on internal audit types at startup
options.Json.Hooks.ShouldSerializeType = type =>
    !type.Namespace?.StartsWith("MyApp.Internal") ?? true;

// Rename any property called "Id" to "identifier" across all types
options.Json.Hooks.ResolvePropertyName = (clrName, type) =>
    clrName == "Id" ? "identifier" : null;

// Suppress any property whose value is an empty string
options.Json.Hooks.ShouldSerializeProperty = (instance, value, clrName, type) =>
    value is not string s || s.Length > 0;

// Log all resolved types and their JSON property names at startup
options.Json.Hooks.OnTypeResolved = (type, jsonNames) =>
    Console.WriteLine($"[JSON] {type.Name}: {string.Join(", ", jsonNames)}");

---

Default Values Reference