Moquestra.TypeIds.SourceGenerator 1.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Moquestra.TypeIds.SourceGenerator --version 1.0.0
                    
NuGet\Install-Package Moquestra.TypeIds.SourceGenerator -Version 1.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Moquestra.TypeIds.SourceGenerator" Version="1.0.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Moquestra.TypeIds.SourceGenerator" Version="1.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Moquestra.TypeIds.SourceGenerator">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Moquestra.TypeIds.SourceGenerator --version 1.0.0
                    
#r "nuget: Moquestra.TypeIds.SourceGenerator, 1.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Moquestra.TypeIds.SourceGenerator@1.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Moquestra.TypeIds.SourceGenerator&version=1.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Moquestra.TypeIds.SourceGenerator&version=1.0.0
                    
Install as a Cake Tool

Moquestra.TypeIds

A library for bidirectional mapping between types and integer IDs.

When to use it

Use it when you need a small, stable identifier for a .NET type:

  • Network messages: send a compact ID instead of a type name, and resolve it to the corresponding type on the receiving side.
  • Save data: serialized type names can become invalid when types are renamed or moved; explicitly assigned IDs remain stable.
  • Handler dispatch: route an incoming ID to the appropriate handler without string comparisons or reflection.

Installation

<ItemGroup>
  <PackageReference Include="Moquestra.TypeIds" Version="1.0.0" />
  <PackageReference Include="Moquestra.TypeIds.SourceGenerator" Version="1.0.0" PrivateAssets="all" />
</ItemGroup>

The runtime library works on its own; the source generator is optional. Library authors should keep the direct Moquestra.TypeIds reference so the dependency reaches their own package, and mark only the generator with PrivateAssets="all".

Supported environments

  • Runtime library: targets netstandard2.1 and is compatible with .NET Core 3.0+ and .NET 5+, but not with .NET Framework.
  • Source generator: requires a Roslyn 4.3+ compiler host — .NET SDK 6.0.400+ or Visual Studio 2022 17.3+. IDE design-time support also requires a compatible Roslyn host; if generated code is missing only in the editor, update the IDE. If the build reports warning CS9057 and TypeIdMap is missing, the host compiler is too old. Generated code compiles under C# 8.0 or later.
  • Trimming and Native AOT: AddFromAssembly discovers types through reflection, so trimmed deployments can remove annotated types and silently skip them. Prefer the source generator there; its typeof references keep the mapped types rooted.

Usage

[TypeId(1)] sealed class LoginRequest { }
[TypeId(2)] sealed class LoginResponse { }
[TypeId]    sealed class HeartbeatCommand { }
[TypeId("Session.Kick")] sealed class KickNotification { }

var registry = new TypeIdRegistry();

// Register every type in the assembly that has a TypeIdAttribute:
registry.AddFromAssembly(typeof(LoginRequest).Assembly);

// Or register types one by one using TypeIdAttribute:
// registry.Add(typeof(LoginRequest));
// registry.Add(typeof(LoginResponse));
// registry.Add(typeof(HeartbeatCommand));
// registry.Add(typeof(KickNotification));

// Or register types with explicit IDs:
// registry.Add(typeof(LoginRequest), 1);
// registry.Add(typeof(LoginResponse), 2);

// Or register types with aliases:
// registry.Add(typeof(KickNotification), "Session.Kick");

registry.TryGetId(typeof(LoginRequest), out var id);
registry.TryGetId(typeof(HeartbeatCommand), out var heartbeatId);
registry.TryGetId(typeof(KickNotification), out var kickId);
registry.TryGetType(2, out var type);

Console.WriteLine($"typeof(LoginRequest) -> {id}");
Console.WriteLine($"typeof(HeartbeatCommand) -> {heartbeatId}");
Console.WriteLine($"typeof(KickNotification) -> {kickId}");
Console.WriteLine($"2 -> {type}");

Output:

typeof(LoginRequest) -> 1
typeof(HeartbeatCommand) -> -416631049
typeof(KickNotification) -> -2036228135
2 -> Moquestra.TypeIds.Sample.LoginResponse
  • A type can be mapped to only one ID, and an ID to only one type.
  • Generic types are not supported. Registering one throws an ArgumentException.
  • Add(Type) determines the ID from the TypeIdAttribute applied to the type and throws an ArgumentException if the attribute is missing.
  • When the attribute specifies neither a nonzero ID nor an alias, the ID is computed from the type's full name. Computed IDs are always negative, so they never collide with positive manual IDs.
  • A string alias — [TypeId("Session.Kick")] or Add(type, "Session.Kick") — is hashed instead of the type's full name, so changing the type's name or namespace does not change the ID.
  • An ID computed from the type's full name changes when the type is renamed or moved to another namespace. To preserve compatibility with persisted data, use the type's previous full name as its alias; this preserves the previous computed ID.
  • If a full name or alias hashes to an ID already mapped to another type, registration throws; assign an explicit ID to either type to resolve the collision.
  • AddFromAssembly registers every type in the assembly that has a TypeIdAttribute. Types without the attribute are ignored, and types registered before a conflict remain in the registry.
  • If a type or ID is already mapped, Add throws an ArgumentException identifying the existing mapping. Rejected duplicate registrations leave the registry unchanged.
  • TryGetType and TryGetId return false when no mapping exists for the supplied ID or type.
  • TypeIdRegistry is not thread-safe. Finish registration on a single thread during startup, and read concurrently only while no further registrations occur.

ID computation

A computed ID is the 32-bit FNV-1a hash of the UTF-8 bytes of the type's full name, or of the alias when one is declared, with the sign bit forced so the result is always negative. This algorithm is a compatibility contract for 1.x, so peers in other languages can reproduce the same IDs.

Lookups always take a Type or an ID; an alias is consumed when the ID is computed at registration or generation time and plays no part in lookups.

Source generator

The Moquestra.TypeIds.SourceGenerator package provides a compile-time alternative to the runtime registry. It collects [TypeId]-annotated types from the current assembly, excluding those that generated code cannot reference, and generates a TypeIdMap class in the project's <RootNamespace>.Generated namespace, falling back to the assembly name when no root namespace is available. Its lookup methods use switch statements, so no registration, reflection, or dictionary is needed at runtime.

Install the generator package alongside the runtime package as shown in Installation. The generated lookup methods mirror the registry's lookup API:

Moquestra.TypeIds.Sample.Generated.TypeIdMap.TryGetType(2, out var mappedType);
Moquestra.TypeIds.Sample.Generated.TypeIdMap.TryGetId(typeof(LoginRequest), out var mappedId);
  • IDs are determined at compile time using the same rules as the runtime registry, so generated and runtime mappings use the same ID for every type handled by both paths.
  • Assemblies with distinct root namespaces get distinct lookup names, so their maps can be referenced side by side.
  • The registry remains available for cases the generator cannot cover, such as assemblies loaded at runtime.

The generator reports these diagnostics:

ID Severity Description
MQTID001 Warning The annotated type is not accessible to the generated lookup and is skipped.
MQTID002 Error The annotated type declares a null or empty alias.
MQTID003 Error An ID is mapped to more than one type.
MQTID004 Error The generated lookup type conflicts with an existing type in the assembly.
MQTID005 Error The annotated type is a generic type, which is not supported.
There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

  • .NETStandard 2.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.2.0 151 9/4/2026
1.1.0 123 8/27/2026
1.0.0 135 8/13/2026