Wireloom.Dds.Generator 0.4.0

Wireloom.Dds.Generator

Wireloom.Dds.Generator is a Roslyn source generator and MSBuild integration for generating C# types from the RTI Connext DDS IDL subset. Add it to a .NET project that owns DDS data contracts; the package generates source during the normal build and does not invoke Java, native tooling, or rtiddsgen.

Consumer projects can target .NET 8 and higher using C# 12 or later. Support is feature-specific and evidence-driven; successful compilation of one IDL shape is not a blanket claim of RTI or wire compatibility.

The example below uses a .NET 8 target and C# 12. Current package integration evidence builds that target using the repository-pinned .NET 10 SDK; the Roslyn hosts in older SDKs are not all qualified. RTI Connext 7.7.0 is the tested runtime baseline.

For a project replacing existing RTI-generated C#, follow the migration guide. It maps common rtiddsgen options, identifies known API differences, and gives a validation and rollback procedure.

Find your task

• Build and run Hello World with a publisher and subscriber.
• Install the package and declare an IDL root.
• Share compiled contracts between applications.
• Understand IDL-to-C# mappings.
• Configure includes, defines, and multiple roots.
• Inspect generated source.
• Look up annotations, diagnostics, and effective limits.
• Troubleshoot generation.

Install

Add the generator and the RTI runtime explicitly. The generator package does not add Rti.ConnextDds transitively because the application owns its runtime version and configuration.

Running the DDS application also requires the RTI runtime's native assets and a valid license for the NuGet.org distribution. Follow RTI's license setup and the Hello World prerequisites.

<ItemGroup>
  <PackageReference Include="Rti.ConnextDds" Version="7.7.0" />
  <PackageReference Include="Wireloom.Dds.Generator"
                    Version="0.4.0"
                    PrivateAssets="all" />
</ItemGroup>

The retained oracle corpus was generated with RTI Connext DDS 7.7.0 / rtiddsgen 4.7.0. Use RTI 7.7.0 as the tested runtime baseline. The package's minimum-version guard accepts 7.3.1 and later; it does not establish that every generated API works with older releases. The consumer project must resolve a compatible Rti.ConnextDds reference.

The generator itself targets netstandard2.0 for Roslyn host compatibility. The repository's .NET 10 build and test defaults do not impose a .NET 10 requirement on consumer applications.

Declare an IDL generation root

Declare each file that starts generation with a DdsIdl item:

<ItemGroup>
  <DdsIdl Include="Contracts\Telemetry.idl" />
</ItemGroup>

The IDL root can include other files. Included files are tracked inputs and are not independently generated as roots.

module Telemetry {
  struct Sample {
    long id;
    string<64> label;
    sequence<float, 8> values;
  };
};

The generated API follows the IDL module structure. For the example above, the consumer can use the generated Telemetry.Sample data type and, when the selected feature shape has type support, Telemetry.SampleSupport:

var sample = new Telemetry.Sample
{
    id = 42,
    label = "temperature"
};

sample.values.Add(20.5F);
sample.values.Add(21.0F);

var typeSupport = Telemetry.SampleSupport.Instance;

For ordinary typed DDS code, use the generated data type with RTI's normal participant, topic, and writer APIs:

using Rti.Dds.Domain;
using Rti.Dds.Topics;

using var participant = DomainParticipantFactory.Instance.CreateParticipant(domainId: 0);
using var topic = participant.CreateTopic<Telemetry.Sample>("Telemetry");
using var writer = participant.ImplicitPublisher.CreateDataWriter(topic);

var sample = new Telemetry.Sample { id = 42, label = "temperature" };
sample.values.Add(20.5F);
writer.Write(sample);

RTI's typed topic API locates the generated type support for Telemetry.Sample. Use Telemetry.SampleSupport.Instance directly when application code needs its utilities, such as DynamicType, a serializer, or formatted output. The support instance does not create a topic or publish data. This example shows the API handoff; it still requires the RTI runtime, its deployment/licensing prerequisites, matching topic/type/QoS on a peer, and a running DDS domain. See RTI's C# publication examples for the broader publish/subscribe lifecycle.

Generated types include the managed data contract and the RTI-specific support surface where the IDL shape is supported: native companions, type support, interpreted plugins, and DynamicType metadata.

Share generated contracts

For types used by several applications, put the DdsIdl roots in one class library and reference that library from each application. The library's build compiles generated C# into its assembly; consumers of the compiled library do not need the generator package unless they also declare their own IDL roots.

<ItemGroup>
  <PackageReference Include="Rti.ConnextDds" Version="7.7.0" />
  <PackageReference Include="Wireloom.Dds.Generator"
                    Version="0.4.0"
                    PrivateAssets="all" />
  <DdsIdl Include="Contracts\Telemetry.idl" />
</ItemGroup>

<ItemGroup>
  <PackageReference Include="Company.Contracts" Version="1.0.0" />
  
  <PackageReference Include="Rti.ConnextDds" Version="7.7.0" />
</ItemGroup>

The normal Rti.ConnextDds reference in the contracts project is a package dependency when that project is packed. Applications can rely on that dependency or reference the runtime explicitly to control resolution. The generator reference uses PrivateAssets="all", so the contracts package does not configure source generation for downstream projects. Generated .g.cs documents are build intermediates; the compiled contracts assembly is the shareable artifact. Check the contracts package's target frameworks against the application before publishing it.

Common IDL-to-C# mappings

These examples show the public C# API generated by Wireloom and compare it with the retained RTI Connext 7.7.0 C# oracle. The comparison is about generated source shape. Wireloom emits the C# contracts and adapters; RTI supplies the sequence types and DDS runtime. See RTI documentation for behavior owned by its runtime. The effective-limits section describes how bounds relate to mutation and DDS processing.

This is a quick reference, not a complete mapping catalog. Consult the feature coverage matrix for case-level status and evidence. A difference in generated C# shape does not by itself establish a difference in DDS wire behavior. The runtime contract coverage matrix indexes tested copy, ownership, optional-presence, union, and native-round-trip behavior.

Configure includes and preprocessing

Use project properties for defaults shared by roots, or root-item metadata for the project-wide generation batch:

<PropertyGroup>
  <DdsIdlIncludeDirectories>
    $(MSBuildProjectDirectory)\Contracts\Shared
  </DdsIdlIncludeDirectories>
</PropertyGroup>

<ItemGroup>
  <DdsIdl Include="Contracts\Telemetry.idl"
          IncludeDirectories="$(MSBuildProjectDirectory)\Contracts\Telemetry"
          Defines="ENABLE_DIAGNOSTICS;PRODUCT_VARIANT=Enterprise"
          Undefines="LEGACY_LAYOUT"
          Strict="true" />
</ItemGroup>

Supported metadata:

The current compiler combines these settings across all generating roots. It does not provide isolated preprocessing or validation settings per root.

Quoted relative includes resolve from the including file's directory. Angle includes use the configured include directories. Keep a shared file as an included input unless it is intentionally a separate generation root.

Project-level include directories are added before root-item directories. Include directories are deduplicated by path, keeping the first occurrence. Quoted includes search the including file's directory first, then the combined include directories; angle includes search the combined directories only. If two search directories contain the same include name, the first matching path wins.

Defines and Undefines are pooled across the generation roots. All external defines seed each root's preprocessor, then all external undefines are applied; an external undefine therefore removes a name even if another root defines it. Each root starts with that same external macro state, so in-file #define and #undef changes do not carry from one root to the next. Avoid assigning different values to the same define in separate roots; per-root values are not isolated. Split variants into separate projects or separate builds when they need different IDL macro or strict-validation settings.

Strict defaults to false. With strict validation off, this inherited-key declaration is accepted; setting Strict="true" on any generation root makes the whole batch reject it with a source-located generation error:

struct Base { @key long tenant; };
struct Derived : Base { @key long localId; };

This is the strict check currently added by Wireloom: a derived struct or valuetype may not declare another @key member. Strict mode does not turn on a general validation suite beyond that check.

Large inputs may hit deterministic preprocessing safety limits. They are not configurable through MSBuild; see preprocessor limits.

Multiple roots and shared IDL

Use multiple roots when one project owns several types that include shared declarations. For example:

Contracts/
  Telemetry.idl
  Commands.idl
  Shared/
    Common.idl

// Shared/Common.idl
#ifndef WIRELOOM_SHARED_COMMON_IDL
#define WIRELOOM_SHARED_COMMON_IDL
module Shared {
  struct Identity { long id; };
};
#endif

// Telemetry.idl
#include <Common.idl>
module Telemetry { struct Sample { Shared::Identity source; long value; }; };

// Commands.idl
#include <Common.idl>
module Commands { struct Request { Shared::Identity source; long action; }; };

Configure the include directory and declare only the two roots:

<PropertyGroup>
  <DdsIdlIncludeDirectories>$(MSBuildProjectDirectory)\Contracts\Shared</DdsIdlIncludeDirectories>
</PropertyGroup>
<ItemGroup>
  <DdsIdl Include="Contracts\Telemetry.idl" />
  <DdsIdl Include="Contracts\Commands.idl" />
</ItemGroup>

The shared file is a tracked input and contributes Shared.Identity to the same generated assembly. Identical shared include output is emitted once for that project. For types used by several application projects, put the roots in one contracts project and reference its assembly from each application. If separate projects independently generate a shared type, each assembly owns a copy with that type's fully qualified name; avoid referencing both copies from the same consumer. Macro-selected variants require separate builds because root metadata is batch-wide.

Inspect generated source

Roslyn exposes generated documents through the IDE. To also write physical generated files under obj, use the standard compiler options:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)generated</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

The package does not create a separate command-line output directory or run a pre-generation step.

Preprocessor limits

Wireloom applies finite deterministic limits to each IDL input. Exceeding a limit stops generation and reports a source-located generation error. These limits have no MSBuild override:

To reduce a failure, simplify or split large IDL inputs, trim unused macro expansions, reduce conditional-expression and macro nesting, and simplify deep include chains. Splitting helps only when each resulting input and its preprocessed output stay within the per-input limits. The preprocessor feature matrix describes which preprocessing forms are implemented or partial.

Annotation reference

This is a reference to behaviors implemented and exercised by the current corpus, not a claim that every OMG or RTI annotation is supported. Annotation effects often appear in RTI DynamicType metadata rather than in the managed C# member signature.

An annotation accepted by RTI is not automatically implemented by Wireloom. For a declaration not listed here, check the exact corpus case and diagnostic; use an unknown-annotation warning as a prompt to verify the generated contract, not as evidence that the annotation is harmless.

Diagnostics

Diagnostics are owned by the generator and use the original IDL/include location where one is available. Review the table's typical actions before adoption; ignored annotations or interfaces and mappings flagged as potentially lossy can affect the generated contract. Configure an individual diagnostic's severity through the consumer's .editorconfig, for example:

[*.idl]
dotnet_diagnostic.DDSG0101.severity = error

The default severities are grouped by diagnostic family: DDSG0001–DDSG0003 are errors, DDSG0101–DDSG0106 are warnings, and DDSG0107 is informational. Warnings do not all mean generation continues: DDSG0102 reports an unsupported annotation use and is followed by a generation error. DDSG0101, DDSG0103, DDSG0104, DDSG0105, and DDSG0106 report cases where generation continues. The diagnostics table describes the action for each one.

Diagnostics point to the originating IDL file, including when the problem is inside an included file. For example, if Contracts/Telemetry.idl contains:

#include "shared/Shared.idl"

and Contracts/shared/Shared.idl contains:

struct Shared {
  long values[0];
};

the DDSG0001 error reports that Array dimensions must be a positive Int32, at the array bound in Shared.idl. If the same declaration is placed directly in Telemetry.idl, the error points to the root file instead. Start from the reported path and line, correct the bound, and rebuild; the build fails while a generation error remains.

Supported boundary

The current corpus exercises modules, structs, nested declarations, aliases, enums, unions, constants, primitive values, narrow and wide strings, bounded strings, sequences, arrays, include graphs, conditional preprocessing, keys, annotations, and extensibility. Several of these are supported only for the specific shapes covered by the retained RTI oracle evidence.

Before adopting a feature, consult the diagnostics table, feature coverage matrix, and corpus rules.

Effective limits for unbounded values

Wireloom currently assigns effective limits to unbounded IDL values: 255 UTF-8 bytes for narrow strings, 255 UTF-16 code units for wide strings, and 100 elements for sequences. For example, 128 copies of é use 256 UTF-8 bytes, so they exceed the narrow-string limit even though the C# string contains only 128 characters.

Generated string properties do not enforce their bounds when assigned, and sequence members expose mutable containers whose Add operations do not cap the element count. RTI uses the bound in type metadata when processing DDS data. The runtime contract suite verifies native round trips at the effective limits. It does not establish exactly where or how an over-limit value fails, so consumers should validate values before DDS processing rather than rely on assignment-time checks.

The compatibility corpus compares source-generation behavior and generated C# shape. It does not automatically prove serialization-byte equivalence, live DDS behavior, or C++ interoperability.

What this package does not do

• It does not provide the RTI DDS runtime, transport, or serialization engine.
• It does not invoke or forward arbitrary arguments to rtiddsgen.
• It does not implicitly generate every .idl file in a project; roots are explicit DdsIdl items.
• It does not promise complete Connext IDL coverage or universal drop-in compatibility with RTI-generated C#.
• It does not silently omit unsupported declarations; accepted exceptions that ignore annotations or interfaces are reported with diagnostics.

Troubleshooting

When generation appears not to run, start with a clean command-line build and follow the symptom table. IDE behavior can depend on its Roslyn host; current package integration evidence covers command-line builds, not every IDE/SDK combination.

The generator reports DDSG0003

Add the runtime package to the consuming project. The generator package is private build tooling; the application must reference Rti.ConnextDds itself.

An include cannot be resolved

Check whether the include is quoted or angle-bracketed. Quoted includes are resolved relative to the including file. For angle includes, add the directory to DdsIdlIncludeDirectories or the root's IncludeDirectories metadata.

A shared file is generated twice

Keep the shared file as an included input and declare only the intended root in DdsIdl. A physical IDL file should normally have one generation identity per consumer project.

A feature is rejected

Read the source-located DDSG0001 diagnostic, then check the feature coverage matrix. Rejection is intentional when the current managed compiler does not have evidence for a safe generated contract.

Learn more

• Wireloom repository
• Architecture overview
• Corpus compliance tests
• Package integration test
• Generated value semantics

RTI-generated reference material in the repository is retained under the applicable RTI license and review rules. It is not redistributed by this NuGet package.