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]

Reply via email to