AbiForge.RoslynGenerator 1.0.5

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 — its src/LumenRTC/LumenRTC.csproj references tools/abi_framework/generator_sdk/csharp/Abi.RoslynGenerator.csproj.

Validation command (LumenRTC example):

dotnet build src/LumenRTC/LumenRTC.csproj