Microsoft.Orleans.Serialization 10.4.0
Microsoft Orleans Serialization
Introduction
Microsoft Orleans Serialization is a fast, flexible, and version-tolerant serializer for .NET. It provides the core serialization capabilities for Orleans, enabling efficient serialization and deserialization of data across the network and for storage.
Getting Started
To use this package, install it via NuGet:
dotnet add package Microsoft.Orleans.Serialization
This package is automatically included when you reference the Orleans SDK or the Orleans client/server metapackages.
Example
// Creating a serializer
var services = new ServiceCollection();
services.AddSerializer();
var serviceProvider = services.BuildServiceProvider();
var serializer = serviceProvider.GetRequiredService<Serializer>();
// Serializing an object
var bytes = serializer.SerializeToArray(myObject);
// Deserializing an object
var deserializedObject = serializer.Deserialize<MyType>(bytes);
Supporting your own Types
To make your types serializable in Orleans, mark them with the [GenerateSerializer] attribute and mark each field/property which should be serialized with the [Id(int)] attribute:
[GenerateSerializer]
public class MyClass
{
[Id(0)]
public string Name { get; set; }
[Id(1)]
public int Value { get; set; }
}
When fail-closed type validation is enabled, additional types can be allowed by configuring TypeManifestOptions.AddAllowedType or TypeManifestOptions.AddAllowedAssembly.
Generated serializers and copiers for C# payloads use ref-returning
UnsafeAccessor methods to read and restore private fields, readonly fields,
and auto-property backing fields on supported targets. Non-generic C# payloads
use this access on .NET 8 and later; generic C# payloads use it on .NET 9 and
later, with the payload's generic constraints preserved. Struct receivers are
passed by reference. This allows NativeAOT-compiled generated code for C#
payloads to restore get-only and init-only properties and to deep-copy values
stored in readonly fields.
Generated C# codecs and copiers emit one ref-returning accessor per field for both reading and writing on supported targets.
The generator selects these capabilities from the SDK's target-framework
identifier and version and verifies that UnsafeAccessorAttribute is available
in the compilation references.
For C# payloads, legacy targets and .NET 8 generic payloads use generated
field-access delegates. Setting OrleansHotReload=true retains lazily
initialized delegates for fields, so existing serializer and copier instances
can access members added by hot reload.
Volatile fields use ref-returning accessors on .NET 10 and later. Earlier targets restore private volatile fields through generated delegates, preserving compatibility with runtimes affected by volatile-field signature matching.
F# record and union field restoration uses the existing generated-delegate strategy on JIT-enabled runtimes.
NativeAOT applications also need statically available codecs, copiers, and activators for their closed payload types.
Documentation
For more comprehensive documentation, please refer to:
Feedback & Contributing
- If you have any issues or would like to provide feedback, please open an issue on GitHub
- Join our community on Discord
- Follow the @msftorleans Twitter account for Orleans announcements
- Contributions are welcome! Please review our contribution guidelines
- This project is licensed under the MIT license
Showing the top 20 packages that depend on Microsoft.Orleans.Serialization.
| Packages | Downloads |
|---|---|
|
Microsoft.Orleans.Journaling
Extensible persistence for grains based on replicated states, including a default System.Text.Json journal format.
|
1 |
.NET 10.0
- Microsoft.Orleans.Serialization.Abstractions (>= 10.4.0)
- Microsoft.CodeAnalysis.Common (>= 5.0.0)
- Microsoft.CodeAnalysis.Workspaces.Common (>= 5.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.5)
- Microsoft.Extensions.DependencyModel (>= 10.0.5)
- Microsoft.Extensions.ObjectPool (>= 10.0.5)
- Microsoft.Extensions.Options (>= 10.0.5)
- System.IO.Hashing (>= 10.0.3)
- Microsoft.CodeAnalysis.Analyzers (>= 5.9.0)
.NET 8.0
- Microsoft.Orleans.Serialization.Abstractions (>= 10.4.0)
- Microsoft.CodeAnalysis.Common (>= 4.5.0)
- Microsoft.CodeAnalysis.Workspaces.Common (>= 4.5.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.DependencyModel (>= 8.0.2)
- Microsoft.Extensions.ObjectPool (>= 8.0.24)
- Microsoft.Extensions.Options (>= 8.0.2)
- System.IO.Hashing (>= 10.0.3)
- Microsoft.CodeAnalysis.Analyzers (>= 5.9.0)
- System.IO.Pipelines (>= 8.0.0)
.NET Standard 2.1
- Microsoft.Orleans.Serialization.Abstractions (>= 10.4.0)
- Microsoft.CodeAnalysis.Common (>= 4.5.0)
- Microsoft.CodeAnalysis.Workspaces.Common (>= 4.5.0)
- Microsoft.DotNet.PlatformAbstractions (>= 3.1.6)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.DependencyModel (>= 8.0.2)
- Microsoft.Extensions.ObjectPool (>= 8.0.24)
- Microsoft.Extensions.Options (>= 8.0.2)
- System.Collections.Immutable (>= 8.0.0)
- System.IO.Hashing (>= 10.0.3)
- Microsoft.CodeAnalysis.Analyzers (>= 5.9.0)
- System.IO.Pipelines (>= 8.0.0)
- System.Text.Json (>= 8.0.5)
| Version | Downloads | Last updated |
|---|---|---|
| 10.4.0 | 1 | 10/12/2026 |
| 10.3.1 | 0 | 08/28/2026 |
| 10.3.0 | 0 | 08/27/2026 |
| 10.3.0-rc.1 | 0 | 08/25/2026 |
| 10.2.2 | 1 | 10/12/2026 |
| 10.2.2-rc.2 | 0 | 07/15/2026 |
| 10.2.2-rc.1 | 0 | 07/10/2026 |
| 10.2.1 | 0 | 06/24/2026 |
| 10.2.1-preview.1 | 0 | 06/19/2026 |
| 10.2.0 | 0 | 06/12/2026 |
| 10.1.1-preview.1 | 0 | 05/13/2026 |
| 10.1.0 | 0 | 04/14/2026 |
| 10.0.1 | 0 | 02/07/2026 |
| 10.0.0 | 0 | 01/20/2026 |
| 10.0.0-rc.2 | 0 | 12/31/2025 |
| 9.2.1 | 0 | 07/16/2025 |
| 9.2.0 | 0 | 07/14/2025 |
| 9.2.0-preview3 | 0 | 06/10/2025 |
| 9.2.0-preview2 | 0 | 06/04/2025 |
| 9.2.0-preview1 | 0 | 04/04/2025 |
| 9.1.2 | 0 | 02/13/2025 |
| 9.0.1 | 0 | 11/23/2024 |
| 9.0.0 | 0 | 11/14/2024 |
| 8.2.0 | 0 | 07/12/2024 |
| 8.2.0-preview1 | 0 | 05/22/2024 |
| 8.1.0 | 0 | 04/17/2024 |
| 8.1.0-preview3 | 0 | 03/11/2024 |
| 8.1.0-preview2 | 0 | 02/23/2024 |
| 8.1.0-preview1 | 0 | 02/13/2024 |
| 8.0.0 | 0 | 01/05/2024 |
| 8.0.0-rc2 | 0 | 12/20/2023 |
| 8.0.0-rc1 | 0 | 12/04/2023 |
| 7.2.7 | 0 | 10/15/2024 |
| 7.2.6 | 0 | 03/09/2024 |
| 7.2.5 | 0 | 02/22/2024 |
| 7.2.4 | 0 | 12/02/2023 |
| 7.2.3 | 0 | 11/03/2023 |
| 7.2.2 | 0 | 10/16/2023 |
| 7.2.1 | 0 | 07/11/2023 |
| 7.2.0 | 0 | 07/07/2023 |
| 7.1.2 | 0 | 04/19/2023 |
| 7.1.1 | 0 | 03/23/2023 |
| 7.1.0 | 0 | 02/01/2023 |
| 7.0.0 | 0 | 11/08/2022 |
| 7.0.0-rc2 | 0 | 10/19/2022 |
| 4.0.0-preview2 | 0 | 08/04/2022 |
| 4.0.0-preview1 | 0 | 02/10/2022 |