Serialization configuration in Orleans

Serialization configuration in Orleans is a crucial part of the overall system design. While Orleans provides reasonable defaults, you can configure serialization to suit your app's needs. For sending data between hosts, Orleans.Serialization supports delegating to other serializers, such as Newtonsoft.Json and System.Text.Json. You can add support for other serializers by following the pattern set by those implementations. For grain storage, it's best to use IGrainStorageSerializer to configure a custom serializer.

Configure Orleans to use Newtonsoft.Json

To configure Orleans to serialize certain types using Newtonsoft.Json, first reference the Microsoft.Orleans.Serialization.NewtonsoftJson NuGet package. Then, configure the serializer, specifying which types it will be responsible for. In the following example, we specify that the Newtonsoft.Json serializer is responsible for all types in the Example.Namespace namespace.

siloBuilder.Services.AddSerializer(serializerBuilder =>
{
    serializerBuilder.AddNewtonsoftJsonSerializer(
        isSupported: type => type.Namespace.StartsWith("Example.Namespace"));
});

In the preceding example, the call to AddNewtonsoftJsonSerializer adds support for serializing and deserializing values using Newtonsoft.Json.JsonSerializer. You must perform similar configuration on all clients that need to handle those types.

For types marked with GenerateSerializerAttribute, Orleans prefers the generated serializer over the Newtonsoft.Json serializer.

Configure Orleans to use System.Text.Json

Alternatively, to configure Orleans to use System.Text.Json to serialize your types, reference the Microsoft.Orleans.Serialization.SystemTextJson NuGet package. Then, configure the serializer, specifying which types it will be responsible for. In the following example, we specify that the System.Text.Json serializer is responsible for all types in the Example.Namespace namespace.

• Install the Microsoft.Orleans.Serialization.SystemTextJson NuGet package.
• Configure the serializer using the AddJsonSerializer method.

Consider the following example when interacting with the ISiloBuilder:

siloBuilder.Services.AddSerializer(serializerBuilder =>
{
    serializerBuilder.AddJsonSerializer(
        isSupported: type => type.Namespace.StartsWith("Example.Namespace"));
});

External serializer providers

Ensure serialization configuration is identical on all clients and silos. Inconsistent configurations can lead to serialization errors.

Specify serialization providers implementing IExternalSerializer using the SerializationProviderOptions.SerializationProviders property of ClientConfiguration and GlobalConfiguration in code:

// Client configuration
var clientConfiguration = new ClientConfiguration();
clientConfiguration.SerializationProviders.Add(
    typeof(FantasticSerializer).GetTypeInfo());

// Global configuration
var globalConfiguration = new GlobalConfiguration();
globalConfiguration.SerializationProviders.Add(
    typeof(FantasticSerializer).GetTypeInfo());

Alternatively, specify them in XML configuration under the <SerializationProviders /> property of <Messaging>:

<Messaging>
    <SerializationProviders>
        <Provider type="GreatCompany.FantasticSerializer, GreatCompany.SerializerAssembly" />
    </SerializationProviders>
</Messaging>

In both cases, you can configure multiple providers. The collection is ordered. This means if a provider capable of serializing types A and B is specified before a provider that can only serialize type B, the latter provider won't be used for type B.