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 07f1e00797 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
07f1e00797 is described below
commit 07f1e00797a642850e7695a8b6f298aef265f01c
Author: chaokunyang <[email protected]>
AuthorDate: Wed Feb 25 15:39:40 2026 +0000
🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
---
docs/compiler/compiler-guide.md | 57 ++++++++++++++++++++++++++++++++-------
docs/compiler/generated-code.md | 59 +++++++++++++++++++++++++++++++++++++++++
docs/compiler/index.md | 15 ++++++-----
docs/compiler/schema-idl.md | 24 +++++++++++++++--
4 files changed, 137 insertions(+), 18 deletions(-)
diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md
index 833ea0d3ff..33c8f6bc9f 100644
--- a/docs/compiler/compiler-guide.md
+++ b/docs/compiler/compiler-guide.md
@@ -63,6 +63,7 @@ Compile options:
| `--cpp_out=DST_DIR` | Generate C++ code in DST_DIR
| (none) |
| `--go_out=DST_DIR` | Generate Go code in DST_DIR
| (none) |
| `--rust_out=DST_DIR` | Generate Rust code in DST_DIR
| (none) |
+| `--csharp_out=DST_DIR` | Generate C# code in DST_DIR
| (none) |
| `--go_nested_type_style` | Go nested type naming: `camelcase`
or `underscore` | from schema/default |
| `--emit-fdl` | Print translated Fory IDL for
non-`.fdl` inputs | `false` |
| `--emit-fdl-path` | Write translated Fory IDL to a file
or directory | (stdout) |
@@ -110,7 +111,7 @@ foryc schema.fdl
**Compile for specific languages:**
```bash
-foryc schema.fdl --lang java,python
+foryc schema.fdl --lang java,python,csharp
```
**Specify output directory:**
@@ -157,7 +158,7 @@ foryc src/main.fdl -I libs/common,libs/types --proto_path
third_party/
foryc schema.fdl --java_out=./src/main/java
# Generate multiple languages to different directories
-foryc schema.fdl --java_out=./java/gen --python_out=./python/src
--go_out=./go/gen
+foryc schema.fdl --java_out=./java/gen --python_out=./python/src
--go_out=./go/gen --csharp_out=./csharp/gen
# Combine with import paths
foryc schema.fdl --java_out=./gen/java -I proto/ -I common/
@@ -226,13 +227,14 @@ Compiling src/main.fdl...
## Supported Languages
-| Language | Flag | Output Extension | Description |
-| -------- | -------- | ---------------- | --------------------------- |
-| Java | `java` | `.java` | POJOs with Fory annotations |
-| Python | `python` | `.py` | Dataclasses with type hints |
-| Go | `go` | `.go` | Structs with struct tags |
-| Rust | `rust` | `.rs` | Structs with derive macros |
-| C++ | `cpp` | `.h` | Structs with FORY macros |
+| Language | Flag | Output Extension | Description |
+| -------- | -------- | ---------------- | ---------------------------- |
+| Java | `java` | `.java` | POJOs with Fory annotations |
+| Python | `python` | `.py` | Dataclasses with type hints |
+| Go | `go` | `.go` | Structs with struct tags |
+| Rust | `rust` | `.rs` | Structs with derive macros |
+| C++ | `cpp` | `.h` | Structs with FORY macros |
+| C# | `csharp` | `.cs` | Classes with Fory attributes |
## Output Structure
@@ -302,6 +304,43 @@ generated/
- Namespace matches package (dots to `::`)
- Header guards and forward declarations
+### C\#
+
+```
+generated/
+└── csharp/
+ └── example/
+ └── example.cs
+```
+
+- Single `.cs` file per schema
+- Namespace uses `csharp_namespace` (if set) or Fory IDL package
+- Includes registration helper and `ToBytes`/`FromBytes` methods
+- Imported schemas are registered transitively (for example `root.idl`
importing
+ `addressbook.fdl` and `tree.fdl`)
+
+### C# IDL Matrix Verification
+
+Run the end-to-end C# IDL matrix (FDL/IDL/Proto/FBS generation plus roundtrip
tests):
+
+```bash
+cd integration_tests/idl_tests
+./run_csharp_tests.sh
+```
+
+This runner executes schema-consistent and compatible roundtrips across:
+
+- `addressbook`, `auto_id`, `complex_pb` primitives
+- `collection` and union/list variants
+- `optional_types`
+- `any_example` (`.fdl`) and `any_example` (`.proto`)
+- `tree` and `graph` reference-tracking cases
+- `monster.fbs` and `complex_fbs.fbs`
+- `root.idl` cross-package import coverage
+- evolving schema compatibility cases
+
+The script also sets `DATA_FILE*` variables so file-based roundtrip paths are
exercised.
+
## Build Integration
### Maven (Java)
diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md
index b433374af1..72225f4fdc 100644
--- a/docs/compiler/generated-code.md
+++ b/docs/compiler/generated-code.md
@@ -685,6 +685,63 @@ if err := restored.FromBytes(data); err != nil {
}
```
+## C\#
+
+### Output Layout
+
+C# output is one `.cs` file per schema, for example:
+
+- `<csharp_out>/addressbook/addressbook.cs`
+
+### Type Generation
+
+Messages generate `[ForyObject]` classes with C# properties and byte helpers:
+
+```csharp
+[ForyObject]
+public sealed partial class Person
+{
+ public string Name { get; set; } = string.Empty;
+ public int Id { get; set; }
+ public List<Person.PhoneNumber> Phones { get; set; } = new();
+ public Animal Pet { get; set; } = null!;
+
+ public byte[] ToBytes() { ... }
+ public static Person FromBytes(byte[] data) { ... }
+}
+```
+
+Unions generate `Union` subclasses with typed case helpers:
+
+```csharp
+public sealed class Animal : Union
+{
+ public static Animal Dog(Dog value) { ... }
+ public static Animal Cat(Cat value) { ... }
+ public bool IsDog => ...;
+ public Dog DogValue() { ... }
+}
+```
+
+### Registration
+
+Each schema generates a registration helper:
+
+```csharp
+public static class AddressbookForyRegistration
+{
+ public static void Register(Fory fory)
+ {
+ fory.Register<addressbook.Animal>((uint)106);
+ fory.Register<addressbook.Person>((uint)100);
+ // ...
+ }
+}
+```
+
+When explicit type IDs are not provided, generated registration uses computed
+numeric IDs (same behavior as other targets).
+
## Cross-Language Notes
### Type ID Behavior
@@ -702,6 +759,7 @@ if err := restored.FromBytes(data); err != nil {
| Rust | `person::PhoneNumber` |
| C++ | `Person::PhoneNumber` |
| Go | `Person_PhoneNumber` (default) |
+| C# | `Person.PhoneNumber` |
### Byte Helper Naming
@@ -712,3 +770,4 @@ if err := restored.FromBytes(data); err != nil {
| Rust | `to_bytes` / `from_bytes` |
| C++ | `to_bytes` / `from_bytes` |
| Go | `ToBytes` / `FromBytes` |
+| C# | `ToBytes` / `FromBytes` |
diff --git a/docs/compiler/index.md b/docs/compiler/index.md
index 0038018790..d6e8bb99be 100644
--- a/docs/compiler/index.md
+++ b/docs/compiler/index.md
@@ -21,7 +21,7 @@ license: |
Fory IDL is a schema definition language for Apache Fory that enables type-safe
cross-language serialization. Define your data structures once and generate
-native data structure code for Java, Python, Go, Rust, and C++.
+native data structure code for Java, Python, Go, Rust, C++, and C#.
## Example Schema
@@ -100,6 +100,7 @@ Generated code uses native language constructs:
- Go: Structs with struct tags
- Rust: Structs with `#[derive(ForyObject)]`
- C++: Structs with `FORY_STRUCT` macros
+- C#: Classes with `[ForyObject]` and registration helpers
## Quick Start
@@ -137,7 +138,7 @@ message Person {
foryc example.fdl --output ./generated
# Generate for specific languages
-foryc example.fdl --lang java,python --output ./generated
+foryc example.fdl --lang java,python,csharp --output ./generated
```
### 4. Use Generated Code
@@ -192,11 +193,11 @@ message Example {
Fory IDL types map to native types in each language:
-| Fory IDL Type | Java | Python | Go | Rust | C++
|
-| ------------- | --------- | -------------- | -------- | -------- |
------------- |
-| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t`
|
-| `string` | `String` | `str` | `string` | `String` |
`std::string` |
-| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool`
|
+| Fory IDL Type | Java | Python | Go | Rust | C++
| C# |
+| ------------- | --------- | -------------- | -------- | -------- |
------------- | -------- |
+| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t`
| `int` |
+| `string` | `String` | `str` | `string` | `String` |
`std::string` | `string` |
+| `bool` | `boolean` | `bool` | `bool` | `bool` | `bool`
| `bool` |
See [Type System](schema-idl.md#type-system) for complete mappings.
diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md
index 4e297aa770..eb9a96dc43 100644
--- a/docs/compiler/schema-idl.md
+++ b/docs/compiler/schema-idl.md
@@ -100,6 +100,7 @@ package com.example.models alias models_v1;
| Go | Package name (last component) |
| Rust | Module name (dots to underscores) |
| C++ | Namespace (dots to `::`) |
+| C# | Namespace |
## File-Level Options
@@ -151,6 +152,25 @@ message Payment {
- The import path can be used in other Go code
- Type registration still uses the Fory IDL package (`payment`) for
cross-language compatibility
+### C# Namespace Option
+
+Override the C# namespace for generated code:
+
+```protobuf
+package payment;
+option csharp_namespace = "MyCorp.Payment.V1";
+
+message Payment {
+ string id = 1;
+}
+```
+
+**Effect:**
+
+- Generated C# files use `namespace MyCorp.Payment.V1;`
+- Output path follows namespace segments (`MyCorp/Payment/V1/` under
`--csharp_out`)
+- Type registration still uses the Fory IDL package (`payment`) for
cross-language compatibility
+
### Java Outer Classname Option
Generate all types as inner classes of a single outer wrapper class:
@@ -285,10 +305,10 @@ For protobuf extension options, see
### Option Priority
-For language-specific packages:
+For language-specific packages/namespaces:
1. Command-line package override (highest priority)
-2. Language-specific option (`java_package`, `go_package`)
+2. Language-specific option (`java_package`, `go_package`, `csharp_namespace`)
3. Fory IDL package declaration (fallback)
**Example:**
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
