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
The following commit(s) were added to refs/heads/main by this push:
new 7fd1fca06 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
7fd1fca06 is described below
commit 7fd1fca06ba5cc9952a08cbd346018895130cf93
Author: chaokunyang <[email protected]>
AuthorDate: Wed Apr 29 16:51:12 2026 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/csharp/field-configuration.md | 57 +++++++++++++++++++++-----------
docs/guide/csharp/index.md | 26 +++++++--------
2 files changed, 50 insertions(+), 33 deletions(-)
diff --git a/docs/guide/csharp/field-configuration.md
b/docs/guide/csharp/field-configuration.md
index 3fc502ee8..0e53eacf2 100644
--- a/docs/guide/csharp/field-configuration.md
+++ b/docs/guide/csharp/field-configuration.md
@@ -21,47 +21,64 @@ license: |
This page covers field-level serializer configuration for C# generated
serializers.
-## `[ForyObject]` and `[Field]`
+## `[ForyObject]` and `[ForyField]`
-Use `[ForyObject]` to enable source-generated serializers. Use `[Field]` to
override integer encoding for a specific field.
+Use `[ForyObject]` to enable source-generated serializers. Use `[ForyField]`
to assign an optional stable field id or to override the Fory schema type used
for a field.
```csharp
using Apache.Fory;
+using S = Apache.Fory.Schema.Types;
[ForyObject]
public sealed class Metrics
{
- // Fixed-width 32-bit encoding
- [Field(Encoding = FieldEncoding.Fixed)]
+ [ForyField(Type = typeof(S.UInt32))]
public uint Count { get; set; }
- // Tagged 64-bit encoding
- [Field(Encoding = FieldEncoding.Tagged)]
+ [ForyField(Type = typeof(S.TaggedUInt64))]
public ulong TraceId { get; set; }
- // Default (varint) encoding
public long LatencyMicros { get; set; }
}
```
-## Available Encodings
+`Id` is optional. When it is omitted, compatible mode still matches the field
by name.
-| Encoding | Meaning |
-| ---------------------- | ----------------------------------------------- |
-| `FieldEncoding.Varint` | Variable-length integer encoding (default) |
-| `FieldEncoding.Fixed` | Fixed-width integer encoding |
-| `FieldEncoding.Tagged` | Tagged integer encoding (`long` / `ulong` only) |
+```csharp
+using Apache.Fory;
+using S = Apache.Fory.Schema.Types;
+
+[ForyObject]
+public sealed class NestedMetrics
+{
+ [ForyField(Type = typeof(S.Map<S.UInt32, S.List<S.TaggedUInt64>>))]
+ public Dictionary<uint, List<ulong?>?> Values { get; set; } = [];
+
+ [ForyField(3, Type = typeof(S.UInt64))]
+ public ulong StableCount { get; set; }
+}
+```
+
+## Schema Descriptor Types
+
+Schema descriptors live under `Apache.Fory.Schema.Types` and are metadata
only. They do not replace normal C# carrier types.
+
+Common scalar descriptors include:
+
+- `S.Int32`, `S.VarInt32`, `S.UInt32`, `S.VarUInt32`
+- `S.Int64`, `S.VarInt64`, `S.TaggedInt64`
+- `S.UInt64`, `S.VarUInt64`, `S.TaggedUInt64`
+- `S.Float16`, `S.BFloat16`, `S.Float32`, `S.Float64`
-## Supported Field Types for Encoding Override
+Container descriptors are composable:
-`[Field(Encoding = ...)]` currently applies to:
+- `S.List<TElement>`
+- `S.Set<TElement>`
+- `S.Map<TKey, TValue>`
-- `int`
-- `uint`
-- `long`
-- `ulong`
+Packed array descriptors such as `S.Int32Array`, `S.UInt32Array`,
`S.Float16Array`, and `S.BFloat16Array` are available when the field should use
the packed array wire type.
-Nullable value variants (for example `long?`) are also handled by generated
serializers.
+Nullability comes from the C# carrier type. Use `List<ulong?>` for nullable
list elements and `NullableKeyDictionary<TKey, TValue>` when a map needs
nullable keys.
## Nullability and Reference Tracking
diff --git a/docs/guide/csharp/index.md b/docs/guide/csharp/index.md
index 95bcac2ac..f0a899c85 100644
--- a/docs/guide/csharp/index.md
+++ b/docs/guide/csharp/index.md
@@ -83,19 +83,19 @@ User decoded = fory.Deserialize<User>(payload);
## Documentation
-| Topic | Description
|
-| --------------------------------------------- |
------------------------------------------------ |
-| [Configuration](configuration.md) | Builder options and runtime
modes |
-| [Basic Serialization](basic-serialization.md) | Typed and dynamic
serialization APIs |
-| [Type Registration](type-registration.md) | Registering user types and
custom serializers |
-| [Custom Serializers](custom-serializers.md) | Implementing `Serializer<T>`
|
-| [Field Configuration](field-configuration.md) | `[Field]` attribute and
integer encoding options |
-| [References](references.md) | Shared/circular reference
handling |
-| [Schema Evolution](schema-evolution.md) | Compatible mode behavior
|
-| [Cross-Language](cross-language.md) | Interoperability guidance
|
-| [Supported Types](supported-types.md) | Built-in and generated type
support |
-| [Thread Safety](thread-safety.md) | `Fory` vs `ThreadSafeFory`
usage |
-| [Troubleshooting](troubleshooting.md) | Common errors and debugging
steps |
+| Topic | Description
|
+| --------------------------------------------- |
--------------------------------------------- |
+| [Configuration](configuration.md) | Builder options and runtime
modes |
+| [Basic Serialization](basic-serialization.md) | Typed and dynamic
serialization APIs |
+| [Type Registration](type-registration.md) | Registering user types and
custom serializers |
+| [Custom Serializers](custom-serializers.md) | Implementing `Serializer<T>`
|
+| [Field Configuration](field-configuration.md) | `[ForyField]` ids and schema
type descriptors |
+| [References](references.md) | Shared/circular reference
handling |
+| [Schema Evolution](schema-evolution.md) | Compatible mode behavior
|
+| [Cross-Language](cross-language.md) | Interoperability guidance
|
+| [Supported Types](supported-types.md) | Built-in and generated type
support |
+| [Thread Safety](thread-safety.md) | `Fory` vs `ThreadSafeFory`
usage |
+| [Troubleshooting](troubleshooting.md) | Common errors and debugging
steps |
## Related Resources
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
