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 b0571ce03b0e66ea24d824439b910315380c18de
Author: chaokunyang <[email protected]>
AuthorDate: Tue Jul 28 02:11:09 2026 +0000

    πŸ”„ synced local 'docs/guide/' with remote 'docs/guide/'
---
 docs/guide/csharp/basic-serialization.md |  39 +++++
 docs/guide/csharp/external-types.md      | 235 +++++++++++++++++++++++++------
 docs/guide/csharp/manual-serializers.md  |   8 +-
 docs/guide/csharp/schema-evolution.md    |  23 ++-
 docs/guide/csharp/schema-metadata.md     |  24 +++-
 docs/guide/csharp/supported-types.md     |  11 ++
 docs/guide/csharp/troubleshooting.md     |  29 ++++
 docs/guide/csharp/type-registration.md   |   6 +
 8 files changed, 321 insertions(+), 54 deletions(-)

diff --git a/docs/guide/csharp/basic-serialization.md 
b/docs/guide/csharp/basic-serialization.md
index a4fc4854c6..6c8e0660c0 100644
--- a/docs/guide/csharp/basic-serialization.md
+++ b/docs/guide/csharp/basic-serialization.md
@@ -62,6 +62,45 @@ byte[] payload = fory.Serialize(person);
 Person decoded = fory.Deserialize<Person>(payload);
 ```
 
+## Class Inheritance
+
+An annotated class includes the supported members declared by its annotated
+base classes in one flattened schema. Annotate every class in the hierarchy
+directly; `[ForyStruct]` is not inherited.
+
+```csharp
+[ForyStruct]
+public abstract class Entity
+{
+    [ForyField(1)]
+    private long _id;
+
+    public long Id => _id;
+}
+
+[ForyStruct]
+public sealed class User : Entity
+{
+    [ForyField(2)]
+    public string Name { get; set; } = string.Empty;
+}
+```
+
+Public and assembly-accessible mutable members are included automatically.
+Private, protected-only, and otherwise inaccessible fields or properties must
+carry `[ForyField]` on the class that declares them. Abstract annotated bases
+publish schema information for concrete descendants but are not registered or
+serialized as roots.
+
+The concrete derived type is still registered once:
+
+```csharp
+fory.Register<User>(102);
+```
+
+For a base class from an unmodifiable package, declare its fields explicitly as
+described in [External Types](external-types.md).
+
 ## Typed API
 
 ### Serialize / Deserialize with byte arrays
diff --git a/docs/guide/csharp/external-types.md 
b/docs/guide/csharp/external-types.md
index 1af23e7988..8ee486f246 100644
--- a/docs/guide/csharp/external-types.md
+++ b/docs/guide/csharp/external-types.md
@@ -21,9 +21,9 @@ 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.
+referenced package or from generated or otherwise unmodifiable source. A local
+declaration supplies the schema while Fory reads and writes the target value
+directly.
 
 ## Class and Struct Targets
 
@@ -34,10 +34,6 @@ namespace ThirdParty;
 
 public sealed class User
 {
-    public User()
-    {
-    }
-
     public string Name { get; set; } = string.Empty;
 
     public int Age { get; set; }
@@ -53,14 +49,26 @@ using S = Apache.Fory.Schema.Types;
 [ForyStruct(Target = typeof(ThirdParty.User))]
 internal abstract class UserSerializer
 {
-    [ForyField(1)]
+    [ForyField(
+        1,
+        TargetDeclaringType = typeof(ThirdParty.User),
+        TargetMemberName = "<Name>k__BackingField")]
     public abstract string Name { get; }
 
-    [ForyField(2, Type = typeof(S.Int32))]
+    [ForyField(
+        2,
+        Type = typeof(S.Int32),
+        TargetDeclaringType = typeof(ThirdParty.User),
+        TargetMemberName = "<Age>k__BackingField")]
     public abstract int Age { get; }
 }
 ```
 
+`Name` and `Age` are the logical wire names. Each declaration maps directly to
+the target's backing field, so the same declaration also accounts for its
+shallow object storage. A public target field can use the default same-name
+mapping.
+
 The declaration is generator input only. Do not instantiate or register
 `UserSerializer`.
 
@@ -78,6 +86,166 @@ internal abstract class PointSerializer
 }
 ```
 
+## Exact Member Mappings
+
+By default, a declaration property binds a visible target field or property
+with the same case-sensitive name. For an external class target, set
+`TargetDeclaringType` and `TargetMemberName` together to bind an exact field
+declared by the target or one of its non-`object` base classes:
+
+```csharp
+[ForyStruct(Target = typeof(ThirdParty.Account))]
+internal abstract class AccountSerializer
+{
+    [ForyField(
+        1,
+        TargetDeclaringType = typeof(ThirdParty.Account),
+        TargetMemberName = "_identifier")]
+    public abstract long Id { get; }
+
+    [ForyField(
+        2,
+        TargetDeclaringType = typeof(ThirdParty.Account),
+        TargetMemberName = "<Secret>k__BackingField")]
+    public abstract string Credential { get; }
+
+    [ForyField(
+        Ignore = true,
+        TargetDeclaringType = typeof(ThirdParty.Account),
+        TargetMemberName = "_cache")]
+    public abstract int CacheStorage { get; }
+}
+```
+
+The declaration property name remains the logical schema name:
+
+- An exact field mapping is both a wire member and a physical storage field.
+- `Ignore = true` contributes an exact field to shallow storage without adding
+  it to the wire schema.
+- Every non-public instance field must be listed exactly once so the shallow
+  graph-memory estimate covers the target's complete instance storage. Static
+  fields are not instance storage.
+
+Fory does not inspect private members in the referenced package. An exact
+private mapping is an application-owned package ABI declaration. Pin and test
+the package version together with the declaration. If a mapped private field
+changes, the generated exact accessor fails with the CLR's missing-field error;
+Fory does not fall back to reflection or another member. An ignored private
+field has no runtime accessor, so validate that storage declaration against the
+pinned package build.
+
+External struct targets support visible field and property mappings only.
+Exact mappings and `Ignore` are class-only because value storage belongs to the
+holder that materializes the struct. An inaccessible pointer field is also
+rejected: without reading private package layout, the generator cannot
+distinguish pointer storage from a fixed buffer. Use a manual serializer for
+these shapes.
+
+## Third-Party Base Classes
+
+An ordinary `[ForyStruct]` class can inherit an unmodifiable third-party class.
+Declare one external hierarchy provider for its immediate third-party base and
+set `BaseOnly = true`.
+
+For example, assume a package defines:
+
+```csharp
+namespace ThirdParty;
+
+public class VendorBase
+{
+    private long _identifier;
+    private string Secret { get; set; } = string.Empty;
+    private readonly int _cache;
+}
+
+public class VendorRecord : VendorBase
+{
+    public int Revision;
+}
+```
+
+A shared schema assembly can declare the complete third-party prefix:
+
+```csharp
+using Apache.Fory;
+
+[ForyStruct(Target = typeof(ThirdParty.VendorRecord), BaseOnly = true)]
+public abstract class VendorRecordHierarchy
+{
+    [ForyField(
+        1,
+        TargetDeclaringType = typeof(ThirdParty.VendorBase),
+        TargetMemberName = "_identifier")]
+    public abstract long Identifier { get; }
+
+    [ForyField(
+        2,
+        TargetDeclaringType = typeof(ThirdParty.VendorBase),
+        TargetMemberName = "<Secret>k__BackingField")]
+    public abstract string Secret { get; }
+
+    [ForyField(
+        Ignore = true,
+        TargetDeclaringType = typeof(ThirdParty.VendorBase),
+        TargetMemberName = "_cache")]
+    public abstract int CacheStorage { get; }
+
+    [ForyField(3)]
+    public abstract int Revision { get; }
+}
+```
+
+The application class then carries its own direct annotation:
+
+```csharp
+[ForyStruct]
+public sealed class LocalRecord : ThirdParty.VendorRecord
+{
+    [ForyField(4)]
+    public string Label { get; set; } = string.Empty;
+}
+```
+
+Register `LocalRecord`. Do not register `ThirdParty.VendorRecord`; a `BaseOnly`
+declaration exists only to support annotated derived classes.
+
+The provider declaration may list exact fields from every third-party ancestor
+of its target. Fory does not discover private package fields. Put a public
+`BaseOnly` declaration in a shared referenced assembly when consumer assemblies
+derive from the same third-party base.
+
+A `BaseOnly` target may be abstract or lack a parameterless constructor as
+long as each concrete annotated child has a legal parameterless construction
+path.
+
+First-party bases use direct `[ForyStruct]` annotations instead. See
+[Class Inheritance](basic-serialization.md#class-inheritance).
+
+## Declaration and Target Requirements
+
+An external structural declaration must be a non-generic abstract class
+containing only abstract get-only declaration properties. Each wire property:
+
+- binds a visible member by the same name or an explicitly named exact field;
+- has the target member's CLR type and generic shape;
+- has matching explicit nullability when the target metadata provides it; and
+- may use the standard `ForyField` ID and schema descriptor options.
+
+When target metadata is nullable-oblivious, the declaration selects schema
+nullability. Members not declared as wire fields keep their constructor or
+derived behavior after deserialization.
+
+A standalone external target must be an accessible concrete class or struct
+with a legal parameterless construction path and writable declared wire state.
+Constructor-bound, factory-only, readonly, init-only, converted, or
+custom-wire targets require a [manual serializer](manual-serializers.md).
+
+Closed generic targets such as `ThirdParty.Box<string>` are supported. On
+.NET 8, a private wire member whose declaring type or signature is generic
+requires a manual serializer. Visible generic members and exact ignored class
+field mappings remain supported. Open generic targets are not supported.
+
 ## Enum Targets
 
 Use an empty static serializer declaration for an enum:
@@ -151,39 +319,9 @@ 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 serialized
-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.
-
-Use `[ForyField(Ignore = true)]` on an additional declaration property when
-non-serialized target storage still needs to contribute to the graph-memory
-estimate. Public target fields are included automatically.
-
-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.
-
-Serialized members 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:
+Set `Evolving` on a standalone external serializer declaration:
 
 ```csharp
 [ForyStruct(
@@ -191,19 +329,26 @@ Set `Evolving` on the serializer declaration:
     Evolving = false)]
 internal abstract class UserSerializer
 {
+    [ForyField(
+        TargetDeclaringType = typeof(ThirdParty.User),
+        TargetMemberName = "<Name>k__BackingField")]
     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.
+declaration. Compatible and schema-consistent modes otherwise behave exactly
+as they do for an ordinary generated C# type.
+
+A `BaseOnly` declaration cannot set `Evolving`; it does not create a root
+serializer. Each concrete annotated descendant owns its own `Evolving`
+setting.
 
 ## 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.
+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.
diff --git a/docs/guide/csharp/manual-serializers.md 
b/docs/guide/csharp/manual-serializers.md
index 0fcf568417..cc05c6a95f 100644
--- a/docs/guide/csharp/manual-serializers.md
+++ b/docs/guide/csharp/manual-serializers.md
@@ -23,9 +23,11 @@ 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.
+mutable third-party targets, including exact private or renamed fields. Use a
+manual serializer for immutable, constructor-only, factory-only, readonly,
+init-only, converted, or custom-wire targets. On .NET 8, a private external
+wire field whose declaring type or accessor signature is generic also requires
+a manual serializer. Exact storage-only mappings do not emit private accessors.
 
 ## Implement `Serializer<T>`
 
diff --git a/docs/guide/csharp/schema-evolution.md 
b/docs/guide/csharp/schema-evolution.md
index 1dca529557..494d087061 100644
--- a/docs/guide/csharp/schema-evolution.md
+++ b/docs/guide/csharp/schema-evolution.md
@@ -30,10 +30,25 @@ 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.
+For a standalone
+[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. Abstract ordinary classes and external `BaseOnly`
+declarations cannot set `Evolving`; each concrete descendant owns that setting.
+
+## Inherited Schemas
+
+A concrete C# class has one flattened schema containing its own wire members
+and those selected by every annotated base. Adding, removing, renaming, or
+changing a base wire member therefore changes the schema of every concrete
+descendant. Rebuild and redeploy descendant assemblies when a base wire
+declaration changes.
+
+Physical fields that are not wire members do not affect field ordering,
+schema hashes, or `TypeMeta`. Rebuild the assembly that owns the annotated base
+or external hierarchy declaration when those fields change. Rebuild dependent
+descendant assemblies when the referenced package's assembly identity changes.
 
 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
diff --git a/docs/guide/csharp/schema-metadata.md 
b/docs/guide/csharp/schema-metadata.md
index 2a7455540c..b764a3c350 100644
--- a/docs/guide/csharp/schema-metadata.md
+++ b/docs/guide/csharp/schema-metadata.md
@@ -27,18 +27,38 @@ Use `[ForyStruct]` to enable source-generated serializers. 
Use `[ForyField]` to
 
 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
+and nullability. A standalone declaration also owns its `Evolving` setting.
+An external `BaseOnly` declaration cannot set `Evolving`; each concrete
+descendant owns that setting. The target supplies the runtime values and
 directly accessed members.
 
 ```csharp
 [ForyStruct(Target = typeof(ThirdParty.User))]
 internal abstract class UserSerializer
 {
-    [ForyField(1)]
+    [ForyField(
+        1,
+        TargetDeclaringType = typeof(ThirdParty.User),
+        TargetMemberName = "<Name>k__BackingField")]
     public abstract string Name { get; }
 }
 ```
 
+## Inherited Fields
+
+The concrete class serializer has one field list containing its own fields and
+the selected fields from every annotated base class. That same flattened list
+drives field ordering, schema hashes, and compatible metadata.
+
+Property overrides contribute one logical field. The nearest override carrying
+`[ForyField]` supplies the ID and schema descriptor. Fields and members hidden
+with `new` remain distinct and must use unique IDs or unique normalized names.
+Duplicate IDs and duplicate name-based identities are generation errors.
+
+Changing a wire member on an annotated base changes every derived schema.
+Rebuild assemblies containing derived serializers after updating the base
+package.
+
 ```csharp
 using Apache.Fory;
 using S = Apache.Fory.Schema.Types;
diff --git a/docs/guide/csharp/supported-types.md 
b/docs/guide/csharp/supported-types.md
index 1b1eccdf78..e6c6250a72 100644
--- a/docs/guide/csharp/supported-types.md
+++ b/docs/guide/csharp/supported-types.md
@@ -77,6 +77,11 @@ This page summarizes built-in and generated type support in 
Apache Foryβ„’ C#.
 ## User Types
 
 - `[ForyStruct]` classes/structs via source-generated serializers
+- Ordinary class hierarchies when every first-party class is directly
+  annotated; the concrete serializer uses one flattened schema
+- Private or protected ordinary base members selected with `[ForyField]`
+- Unmodified third-party base hierarchies described by one explicit external
+  declaration
 - `[ForyEnum]` enums and `[ForyUnion]` ADT records
 - External class, struct, and enum targets through serializer declarations
 - Manual serializer types registered through `Register<T, TSerializer>(...)`
@@ -85,6 +90,12 @@ This page summarizes built-in and generated type support in 
Apache Foryβ„’ C#.
 `[ForyEnum]` numeric values are unsigned 32-bit wire tags and must be in the
 range `0..uint.MaxValue`.
 
+Open generic generated targets are unsupported. A non-generic ordinary class
+may derive from a closed third-party generic base when an external declaration
+describes that exact closed base. On .NET 8, private wire members whose
+declaring type or signature is generic are unsupported; visible members and
+explicit storage-only field declarations remain supported.
+
 ## Dynamic Types
 
 Dynamic object payloads via `Serialize<object?>` / `Deserialize<object?>` 
support:
diff --git a/docs/guide/csharp/troubleshooting.md 
b/docs/guide/csharp/troubleshooting.md
index e5d6bb6bd6..34b51ed91f 100644
--- a/docs/guide/csharp/troubleshooting.md
+++ b/docs/guide/csharp/troubleshooting.md
@@ -78,6 +78,35 @@ same-schema payloads.
 Fory fory = Fory.Builder().TrackRef(true).Build();
 ```
 
+## Derived Class Reports `FORY019`
+
+**Cause**: A non-`object` base class does not expose exactly one compatible
+generated hierarchy declaration. This usually means a first-party base is
+missing its own direct `[ForyStruct]`, the base package was built with an older
+generator, or two referenced schema assemblies declare the same third-party
+base.
+
+**Fix**:
+
+- Add `[ForyStruct]` directly to every modifiable base class and rebuild the
+  base assembly.
+- For an unmodifiable base, reference exactly one external declaration with
+  `Target` set to the derived type's immediate third-party base.
+- Remove duplicate provider assemblies and rebuild descendants.
+
+Fory does not inspect a referenced package's private fields to replace a
+missing declaration.
+
+## Private External Field Throws `MissingFieldException`
+
+**Cause**: An exact external field declaration no longer matches the installed
+package version. `TargetDeclaringType`, `TargetMemberName`, or the declared CLR
+type differs from the package's private application binary interface.
+
+**Fix**: Check the member metadata against the exact package version, update
+the external declaration and its storage-only field entries, then rebuild.
+There is no reflection or alternate-member fallback.
+
 ## Concurrency Issues
 
 **Cause**: Sharing a single `Fory` instance across threads.
diff --git a/docs/guide/csharp/type-registration.md 
b/docs/guide/csharp/type-registration.md
index ccba896463..6496348dc8 100644
--- a/docs/guide/csharp/type-registration.md
+++ b/docs/guide/csharp/type-registration.md
@@ -83,6 +83,12 @@ fory.Register<Order>(101);
 - 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.
+- Register a concrete derived class by its concrete type. Annotated abstract
+  bases and external declarations with `BaseOnly = true` are schema providers
+  for descendants and are not registered.
+- Annotate every first-party class in a serializable hierarchy directly.
+  Registering a derived class does not make an unannotated base class
+  serializable.
 - 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.
 


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to