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]
