# generator_sdk/csharp — Roslyn C# source generator

Roslyn source generator that converts ABI metadata into C# interop code
during compilation.

> **Location note:** This generator lives under `generator_sdk/csharp/` rather than next to the
> Python generators because it is a compiled Roslyn analyzer (netstandard2.0 DLL) that runs
> inside the .NET compiler pipeline — not an external CLI script. It is wired via
> `ProjectReference … OutputItemType="Analyzer"` in the consuming `.csproj`.

## Input

- ABI IDL JSON (for example `abi/generated/mylib/mylib.idl.json`; LumenRTC uses `abi/generated/lumenrtc/lumenrtc.idl.json`).
- Managed handle metadata JSON (for example `abi/bindings/mylib.managed.json`).
- Managed API metadata JSON (for example `abi/bindings/mylib.managed_api.json`).
- MSBuild properties passed through `CompilerVisibleProperty`:
  - `AbiIdlPath`
  - `AbiManagedMetadataPath`
  - `AbiManagedApiMetadataPath`
  - `AbiNamespace`
  - `AbiClassName`
  - `AbiConstantsClassName`
  - `AbiAccessModifier`
  - `AbiCallingConvention`
  - `AbiLibraryExpression`

## Output

- Generated `NativeMethods` (`DllImport`) source.
- Generated `NativeTypes` source (enums/structs/delegates/constants).
- Generated `NativeHandles` source (`SafeHandle` partial methods for release/lifetime).
- Generated managed API sources from `managed_api` metadata:
  callbacks, builder extensions, handle API wrappers, async wrappers.
- All generated sources are added directly to compilation (no checked-in `*.g.cs` required).

### Managed API `output_hints`

`managed_api.output_hints` supports rich hint-name shaping:

- `pattern`: template tokens include:
  `{section}`, `{section_pascal}`, `{section_snake}`, `{section_kebab}`, `{section_path}`,
  `{default}`, `{default_stem}`, `{default_name}`,
  `{namespace}`, `{namespace_path}`.
- `suffix`: appended when hint has no `.cs` extension.
- `sections`: per-section overrides map.
- Built-in managed API emissions are class-driven: section keys come from class names, not fixed labels.
- Canonical keys only: `pattern`, `suffix`, `sections`.

### Managed API `auto_abi_surface`

`managed_api.auto_abi_surface` can auto-generate low-level ABI forwarding methods for each
managed handle class directly from IDL function signatures, plus global ABI entrypoints.
The generated methods live in dedicated internal surface classes
(`{HandleClass}{SectionSuffixPascal}` and global `{GlobalClass}{SectionSuffixPascal}`),
so user-facing handle classes stay clean.

- `enabled`: toggles auto-surface generation.
- `method_prefix`: prefix for generated methods (default: `Abi`).
- `section_suffix`: output-hint section suffix for generated per-class sections.
- `global_section`: output-hint section stem for non-handle ABI functions (default: `global`).
- `global_class`: class stem for non-handle ABI functions (default: `Global`).
- `include_deprecated`: include deprecated IDL functions when `true`.
- `coverage`: strict ABI classification gate:
  - `strict`: fail generation if a non-waived ABI function is not classified/emitted.
  - `waived_functions`: optional explicit waivers (`"name"` or `{ "name", "reason" }`).
- `public_facade`: optional public extension layer over internal ABI surface:
  - `enabled`: toggles public facade generation.
  - `class_suffix`: suffix for generated facade class names.
  - `method_prefix`: public method prefix (default: `Raw`).
  - `typed_method_prefix`: prefix for generated typed-wrapper methods (default: `Typed`).
  - `section_suffix`: output-hint section suffix for facade sections.
  - `allow_int_ptr`: allow `IntPtr`/`nint` signatures in public facade.
  - `safe_facade`: optional safe/task facade over raw/typed:
    - `enabled`: toggles safe facade generation.
    - `class_suffix`: suffix for safe facade class names.
    - `method_prefix`: prefix for throwing/safe methods.
    - `try_method_prefix`: prefix for `Try*` status wrappers.
    - `async_method_suffix`: suffix for callback-lifted task methods.
    - `section_suffix`: output-hint section suffix for safe facade sections.
    - `exception_type`: exception type used for safe wrapper failures.

### Interop Binding Overrides

The generator consumes `bindings.interop` metadata embedded in IDL:

- `struct_layout_overrides`: per-struct `StructLayout` overrides (`pack`, optional `layout`).
- `callback_typedef_call_tokens`: optional allowed calling-convention tokens for callback typedef parsing.
- `callback_struct_suffixes`: optional callback-struct suffix list (default: `["_callbacks_t"]`).
- `functions.<name>.parameters.<param>`:
  - `managed_type`
  - `modifier` (`ref` / `out` / `in` / `none`)
  - `marshal_as_i1` or `marshal_as: "i1"`
- `output_hints` for interop source hint naming (`abi`, `types`, `handles`):
  - tokens: `{section}`, `{section_pascal}`, `{section_snake}`, `{section_kebab}`, `{section_path}`,
    `{class}`, `{class_path}`, `{namespace}`, `{namespace_path}`, `{target}`,
    `{default}`, `{default_stem}`, `{default_name}`
  - canonical keys: `pattern`, `suffix`, `sections`

### Managed API Optional Sections

`managed_api` supports optional built-in sections:

- `callbacks`
- `builder`
- `handle_api`
- `peer_connection_async`

and optional extensibility sections:

- `custom_sections[]` entries with:
  - `name` (output-hint section key)
  - `class`
  - `methods`
  - optional `default_hint`

## Handle Contracts

For each handle entry in managed metadata, project source may declare a matching
type (`namespace` + `cs_type`) as:

- `partial class`
- inheriting `System.Runtime.InteropServices.SafeHandle`
- accessibility matching metadata (`public` or `internal`)

If a handle type is missing in project source, generator emits a fallback `SafeHandle`
class from metadata and reports a warning (`ABIGEN008`) instead of failing generation.

Violations are reported as source-generator diagnostics (`ABIGEN008`-`ABIGEN012`).

## Integration

Wire the generator from your `.csproj` as an analyzer project reference and pass IDL + managed
metadata files as `AdditionalFiles`. For a complete example, see
[LumenRTC](https://github.com/vitkuz573/LumenRTC) — its `src/LumenRTC/LumenRTC.csproj` references
`tools/abi_framework/generator_sdk/csharp/Abi.RoslynGenerator.csproj`.

Validation command (LumenRTC example):

```bash
dotnet build src/LumenRTC/LumenRTC.csproj
```
