This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 1070cdbf4a7d08d87119b5629179e55767bde2c7 Author: chaokunyang <[email protected]> AuthorDate: Mon Jul 27 09:27:58 2026 +0000 π synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/csharp/basic-serialization.md | 3 +- docs/guide/csharp/external-types.md | 211 +++++++++++++++++++++ docs/guide/csharp/index.md | 11 +- ...custom-serializers.md => manual-serializers.md} | 14 +- docs/guide/csharp/references.md | 5 + docs/guide/csharp/schema-evolution.md | 6 + docs/guide/csharp/schema-metadata.md | 15 ++ docs/guide/csharp/supported-types.md | 7 +- docs/guide/csharp/type-registration.md | 9 +- docs/guide/csharp/xlang-serialization.md | 6 + 10 files changed, 273 insertions(+), 14 deletions(-) diff --git a/docs/guide/csharp/basic-serialization.md b/docs/guide/csharp/basic-serialization.md index 5c88675bc8..a4fc4854c6 100644 --- a/docs/guide/csharp/basic-serialization.md +++ b/docs/guide/csharp/basic-serialization.md @@ -127,7 +127,8 @@ fory.Serialize<object?>(dynamicWriter, value); - Reuse the same `Fory` or `ThreadSafeFory` instance for better performance. - Primitive types and collections do not require user registration. -- User `[ForyStruct]`, `[ForyEnum]`, `[ForyUnion]`, and custom serializer types should be registered explicitly. +- Register user types handled by `[ForyStruct]`, `[ForyEnum]`, `[ForyUnion]`, + external structural serializers, or manual serializers explicitly. ## Related Topics diff --git a/docs/guide/csharp/external-types.md b/docs/guide/csharp/external-types.md new file mode 100644 index 0000000000..d9678d5d38 --- /dev/null +++ b/docs/guide/csharp/external-types.md @@ -0,0 +1,211 @@ +--- +title: External Types +sidebar_position: 6 +id: external_types +license: | + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--- + +External-type serialization generates a serializer for a class, struct, or +enum that cannot carry its own Fory annotation. The target can come from a +referenced assembly or from generated or otherwise unmodifiable source in the +consumer project. A local serializer declaration supplies the schema, while +Fory reads and writes the target value directly. + +## Class and Struct Targets + +Suppose another package defines this class: + +```csharp +namespace ThirdParty; + +public sealed class User +{ + public User() + { + } + + public string Name { get; set; } = string.Empty; + + public int Age { get; set; } +} +``` + +Declare its external structural serializer in your project: + +```csharp +using Apache.Fory; +using S = Apache.Fory.Schema.Types; + +[ForyStruct(Target = typeof(ThirdParty.User))] +internal abstract class UserSerializer +{ + [ForyField(1)] + public abstract string Name { get; } + + [ForyField(2, Type = typeof(S.Int32))] + public abstract int Age { get; } +} +``` + +The declaration is generator input only. Do not instantiate or register +`UserSerializer`. + +The same form supports an external struct: + +```csharp +[ForyStruct(Target = typeof(ThirdParty.Point))] +internal abstract class PointSerializer +{ + [ForyField(1)] + public abstract int X { get; } + + [ForyField(2)] + public abstract int Y { get; } +} +``` + +## Enum Targets + +Use an empty static serializer declaration for an enum: + +```csharp +[ForyEnum(Target = typeof(ThirdParty.Status))] +internal static class StatusSerializer +{ +} +``` + +The target enum's numeric values are authoritative. Do not copy its constants +into the declaration. Every serialized numeric value must fit in the unsigned +32-bit Fory enum tag range. + +## Registration and Root Values + +Register the target through the normal APIs: + +```csharp +Fory fory = Fory.Builder().Build(); +fory.Register<ThirdParty.User>(100); +fory.Register<ThirdParty.Status>("example.Status"); + +byte[] bytes = fory.Serialize(user); +ThirdParty.User decoded = fory.Deserialize<ThirdParty.User>(bytes); +``` + +The split namespace/name overloads and `ThreadSafeFory` registration work the +same way. There is no separate external-type registration or root API. + +## Fields and Carriers + +Use the target type directly in generated models: + +```csharp +[ForyStruct] +public sealed class Group +{ + public ThirdParty.User Owner { get; set; } = new(); + + public List<ThirdParty.User> Users { get; set; } = []; + + public Dictionary<string, ThirdParty.User> UsersByName { get; set; } = []; +} +``` + +Root carrier composition also uses the ordinary typed API: + +```csharp +byte[] bytes = fory.Serialize(new List<ThirdParty.User> { user }); + +List<ThirdParty.User> decoded = + fory.Deserialize<List<ThirdParty.User>>(bytes); +``` + +External children are supported through the concrete carrier types already +supported by the C# runtime: + +- `Nullable<T>` for external structs and one-dimensional `T[]`; +- `List<T>`, `LinkedList<T>`, `Queue<T>`, and `Stack<T>`; +- `HashSet<T>`, `SortedSet<T>`, and `ImmutableHashSet<T>`; +- `Dictionary<TKey, TValue>`, `SortedDictionary<TKey, TValue>`, + `SortedList<TKey, TValue>`, `ConcurrentDictionary<TKey, TValue>`, and + `NullableKeyDictionary<TKey, TValue>`. + +Targets can appear as map keys or values and inside recursively nested +carriers. Collection interface types are not supported as generated fields or +typed roots. + +## Declaration and Target Requirements + +An external structural serializer declaration must be a non-generic abstract +class containing only abstract get-only schema properties. Each property: + +- matches an accessible target field or property with the same case-sensitive + name; +- has the same CLR type and generic shape; +- has matching explicit nullability when the target metadata provides it; +- can be read and assigned directly by generated code; +- may use the standard `ForyField` ID and schema descriptor options. + +When target metadata is nullable-oblivious, the declaration selects schema +nullability. Only members declared by the serializer are serialized; other +target state keeps its normal default or derived behavior after +deserialization. + +The target must be an accessible concrete class or struct with a legal +parameterless construction path and writable state. Closed generic targets, +such as `ThirdParty.Box<string>`, are supported; open generic targets are not. + +Targets that require private access, readonly or init-only assignment, +constructor arguments, factories, member renaming, or value conversion require +a [manual serializer](manual-serializers.md). + +## Schema Evolution + +Set `Evolving` on the serializer declaration: + +```csharp +[ForyStruct( + Target = typeof(ThirdParty.User), + Evolving = false)] +internal abstract class UserSerializer +{ + public abstract string Name { get; } +} +``` + +Field IDs, field names, schema descriptors, and `Evolving` come from the +declaration. Compatible and schema-consistent modes otherwise behave exactly as +they do for an ordinary generated C# type. + +## Dynamic Values and References + +After registering the target, it can appear in `object`-based dynamic +roots, fields, collections, and maps. Register every concrete target that can +appear dynamically. + +Mutable external classes retain shared-reference and cycle support when +reference tracking is enabled. External structs remain inline values. + +This feature does not add arbitrary interface or base-class polymorphism. + +## Related Topics + +- [Schema Metadata](schema-metadata.md) +- [Type Registration](type-registration.md) +- [Manual Serializers](manual-serializers.md) +- [References](references.md) +- [Schema Evolution](schema-evolution.md) diff --git a/docs/guide/csharp/index.md b/docs/guide/csharp/index.md index f2a41a25e8..5623e26987 100644 --- a/docs/guide/csharp/index.md +++ b/docs/guide/csharp/index.md @@ -26,7 +26,9 @@ Apache Foryβ’ C# is a high-performance, cross-language serialization library fo - High performance binary serialization for .NET 8+ - Xlang compatibility with Fory implementations in Java, Python, C++, Go, Rust, JavaScript/TypeScript, Swift, Dart, Scala, and Kotlin -- Source-generator-based serializers for `[ForyStruct]` types, plus `[ForyEnum]` and `[ForyUnion]` registration +- Source-generator-based serializers for `[ForyStruct]` types, plus + `[ForyEnum]` and `[ForyUnion]` registration +- Generated serializers for external class, struct, and enum targets - Optional reference tracking for shared and circular object graphs - Compatible mode for schema evolution - Thread-safe wrapper (`ThreadSafeFory`) for multi-threaded services @@ -80,7 +82,7 @@ User decoded = fory.Deserialize<User>(payload); - `Serialize<T>(in T value)` / `Deserialize<T>(...)` - `Serialize<object?>(...)` / `Deserialize<object?>(...)` for dynamic payloads - `Register<T>(uint typeId)` and name registration APIs -- `Register<T, TSerializer>(...)` for custom serializers +- `Register<T, TSerializer>(...)` for manual serializers ## Documentation @@ -90,8 +92,9 @@ User decoded = fory.Deserialize<User>(payload); | [Basic Serialization](basic-serialization.md) | Typed and dynamic serialization APIs | | [Xlang Serialization](xlang-serialization.md) | Interoperability guidance | | [Schema Metadata](schema-metadata.md) | `[ForyField]` ids and schema type descriptors | -| [Type Registration](type-registration.md) | Registering user types and custom serializers | -| [Custom Serializers](custom-serializers.md) | Implementing `Serializer<T>` | +| [Type Registration](type-registration.md) | Registering user types and manual serializers | +| [External Types](external-types.md) | Serializers for third-party types | +| [Manual Serializers](manual-serializers.md) | Implementing `Serializer<T>` | | [References](references.md) | Shared/circular reference handling | | [Schema Evolution](schema-evolution.md) | Compatible mode behavior | | [Supported Types](supported-types.md) | Built-in and generated type support | diff --git a/docs/guide/csharp/custom-serializers.md b/docs/guide/csharp/manual-serializers.md similarity index 84% rename from docs/guide/csharp/custom-serializers.md rename to docs/guide/csharp/manual-serializers.md index 4db844dfe9..0fcf568417 100644 --- a/docs/guide/csharp/custom-serializers.md +++ b/docs/guide/csharp/manual-serializers.md @@ -1,7 +1,7 @@ --- -title: Custom Serializers +title: Manual Serializers sidebar_position: 11 -id: custom_serializers +id: manual_serializers license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -19,7 +19,13 @@ license: | limitations under the License. --- -Use custom serializers when a type is not generated with `[ForyStruct]` or requires specialized encoding. +Use a manual serializer when a type is not generated with `[ForyStruct]` or +requires specialized encoding. + +[External-type serialization](external-types.md) generates serializers for +accessible mutable third-party targets. Use a manual serializer for immutable, +constructor-only, factory-only, inaccessible, renamed, converted, or +custom-wire targets. ## Implement `Serializer<T>` @@ -80,7 +86,7 @@ fory.Register<Point, PointSerializer>("com.example.Point"); 1. Keep serializers deterministic and symmetric. 2. Use varint/fixed/tagged encoding intentionally for integer-heavy payloads. -3. Register custom serializers on all reader/writer peers. +3. Register manual serializers on all reader/writer peers. 4. Prefer generated `[ForyStruct]` serializers for normal domain models. ## Related Topics diff --git a/docs/guide/csharp/references.md b/docs/guide/csharp/references.md index 6b6b2363c0..56c3c68bd0 100644 --- a/docs/guide/csharp/references.md +++ b/docs/guide/csharp/references.md @@ -34,6 +34,10 @@ When enabled: - Shared object identity is preserved. - Circular object graphs can be serialized/deserialized safely. +Mutable classes handled by +[external-type serialization](external-types.md) use the same reference +tracking. External structs remain inline values. + ## Circular Reference Example ```csharp @@ -73,4 +77,5 @@ supported; Fory rejects unresolved refs instead of returning a partial union. - [Configuration](configuration.md) - [Basic Serialization](basic-serialization.md) +- [External Types](external-types.md) - [Thread Safety](thread-safety.md) diff --git a/docs/guide/csharp/schema-evolution.md b/docs/guide/csharp/schema-evolution.md index 8143343e15..1dca529557 100644 --- a/docs/guide/csharp/schema-evolution.md +++ b/docs/guide/csharp/schema-evolution.md @@ -30,6 +30,11 @@ Fory fory = Fory.Builder() Compatible mode writes type metadata that allows readers and writers with different struct definitions to interoperate. +For an [external structural serializer](external-types.md), field names, field +IDs, schema descriptors, and the `Evolving` setting come from the local +serializer declaration. Register the third-party target with the same stable +wire identity on every version. + Compatible readers also tolerate selected scalar field type changes when the value is lossless. A matched field can read between `bool`, `string`, numeric scalars, and `decimal` when the converted value has the same logical value. Boolean strings must be exactly `"0"`, `"1"`, `"true"`, or @@ -95,5 +100,6 @@ Because C# uses the xlang wire format only, use `Compatible(false)` only after v ## Related Topics - [Configuration](configuration.md) +- [External Types](external-types.md) - [Type Registration](type-registration.md) - [Troubleshooting](troubleshooting.md) diff --git a/docs/guide/csharp/schema-metadata.md b/docs/guide/csharp/schema-metadata.md index 7c4194d0d6..2a7455540c 100644 --- a/docs/guide/csharp/schema-metadata.md +++ b/docs/guide/csharp/schema-metadata.md @@ -25,6 +25,20 @@ This page covers schema metadata for C# generated serializers. Use `[ForyStruct]` to enable source-generated serializers. Use `[ForyField]` to assign an optional stable non-negative field id or to override the Fory schema type used for a field. +External-type serialization puts `Target` on a local abstract serializer +declaration. Its properties own the field names, IDs, schema descriptors, +nullability, and `Evolving` setting. The target supplies the runtime values and +directly accessed members. + +```csharp +[ForyStruct(Target = typeof(ThirdParty.User))] +internal abstract class UserSerializer +{ + [ForyField(1)] + public abstract string Name { get; } +} +``` + ```csharp using Apache.Fory; using S = Apache.Fory.Schema.Types; @@ -119,5 +133,6 @@ public abstract partial record Shape ## Related Topics - [Configuration](configuration.md) +- [External Types](external-types.md) - [Schema Evolution](schema-evolution.md) - [Supported Types](supported-types.md) diff --git a/docs/guide/csharp/supported-types.md b/docs/guide/csharp/supported-types.md index 3148694ade..db6236377b 100644 --- a/docs/guide/csharp/supported-types.md +++ b/docs/guide/csharp/supported-types.md @@ -76,8 +76,10 @@ This page summarizes built-in and generated type support in Apache Foryβ’ C#. ## User Types -- `[ForyStruct]` classes/structs via source-generated serializers, plus `[ForyEnum]` enums and `[ForyUnion]` ADT records -- Custom serializer types registered through `Register<T, TSerializer>(...)` +- `[ForyStruct]` classes/structs via source-generated serializers +- `[ForyEnum]` enums and `[ForyUnion]` ADT records +- External class, struct, and enum targets through serializer declarations +- Manual serializer types registered through `Register<T, TSerializer>(...)` - `Union` / `Union2<...>` typed union support ## Dynamic Types @@ -96,5 +98,6 @@ Dynamic object payloads via `Serialize<object?>` / `Deserialize<object?>` suppor ## Related Topics - [Basic Serialization](basic-serialization.md) +- [External Types](external-types.md) - [Type Registration](type-registration.md) - [Xlang Serialization](xlang-serialization.md) diff --git a/docs/guide/csharp/type-registration.md b/docs/guide/csharp/type-registration.md index bd9f54edc7..ccba896463 100644 --- a/docs/guide/csharp/type-registration.md +++ b/docs/guide/csharp/type-registration.md @@ -54,14 +54,14 @@ separately: fory.Register<User>("com.example", "User"); ``` -## Register a Custom Serializer +## Register a Manual Serializer ```csharp Fory fory = Fory.Builder().Build(); fory.Register<MyType, MyTypeSerializer>(200); ``` -Name-based custom serializer registration is also supported: +Name-based manual serializer registration is also supported: ```csharp fory.Register<MyType, MyTypeSerializer>("com.example.MyType"); @@ -81,11 +81,14 @@ fory.Register<Order>(101); - Register user-defined types on both writer and reader sides. - Keep ID/name mappings consistent across services and languages. +- For external-type serialization, register the third-party target, such as + `fory.Register<ThirdParty.User>(100)`, not the local serializer declaration. - For the split overloads, `typeName` must be non-empty and must not contain dots. - Register before high-volume serialization workloads to avoid missing type metadata. ## Related Topics - [Basic Serialization](basic-serialization.md) -- [Custom Serializers](custom-serializers.md) +- [External Types](external-types.md) +- [Manual Serializers](manual-serializers.md) - [Xlang Serialization](xlang-serialization.md) diff --git a/docs/guide/csharp/xlang-serialization.md b/docs/guide/csharp/xlang-serialization.md index bf3c76c1b8..2bba643323 100644 --- a/docs/guide/csharp/xlang-serialization.md +++ b/docs/guide/csharp/xlang-serialization.md @@ -50,6 +50,11 @@ fory.Register<Person>(100); Use the same ID mapping on all languages. +Third-party classes, structs, and enums can use +[external-type serialization](external-types.md). Register the target type, +not its local serializer declaration, with the same ID or name used by the +other language peers. + ## Register by Name ```csharp @@ -125,5 +130,6 @@ C# `List<T>` maps to Fory `list<T>`. Use the schema marker ## Related Topics - [Type Registration](type-registration.md) +- [External Types](external-types.md) - [Schema Evolution](schema-evolution.md) - [Supported Types](supported-types.md) --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
