Universal.CodeGeneration.CSharp 1.3.1

Universal.CodeGeneration.CSharp

A library for generating C# source code from various specifications, specializing in strongly-typed HTTP clients and URI builders.

Classes

HttpServiceClientGenerator

Generates complete, strongly-typed HTTP service client code from API specifications (such as OpenAPI/Swagger). It handles the generation of methods, request/response models, enums, and hierarchical resource navigation.

// Parse the OpenAPI JSON
string json = File.ReadAllText("openapi.json");
var spec = HttpServiceClientGenerator.ApiSpecification.FromOpenApi(json);

// Configure generation options
var options = new HttpServiceClientGenerator.Options
{
    BaseClass = HttpServiceClientGenerator.BaseClientType.JsonHttpServiceClient,
    GenerateModelClasses = true,
    UseHierarchicalResources = true,
    JsonSerializer = HttpServiceClientGenerator.JsonSerializerType.SystemTextJson
};

// Generate the code
var generator = new HttpServiceClientGenerator("MyApi.Client", "ApiClient", options);
string sourceCode = generator.Generate(spec);

Target framework compatibility

By default the generated client targets the latest BCL surface (using overloads that accept a CancellationToken, such as HttpContent.ReadAsStringAsync(CancellationToken)). Set TargetFramework to a target framework moniker when the generated code must compile against an older target — including .NET Standard and .NET Framework, where those overloads do not exist:

var options = new HttpServiceClientGenerator.Options
{
    BaseClass = HttpServiceClientGenerator.BaseClientType.JsonHttpServiceClient,
    // e.g. "net10.0", "netstandard2.1", "netstandard2.0", "netcoreapp3.1", "net48"
    TargetFramework = "netstandard2.0"
};

The moniker is resolved to BCL capability flags internally. Targets below .NET 5 (all netstandard*, netcoreapp*, and .NET Framework monikers) omit the newer CancellationToken overloads; net5.0 and later use them. A null, empty, or unrecognized value means "latest" and emits the newest API surface, so it automatically tracks future .NET versions without a code change.

Nullable reference types

By default the generated file opts into the nullable annotation context (so emitted annotations such as string? are valid even though generated files do not inherit the consuming project's nullable context) while keeping nullable warnings off, so the generated code never surfaces warnings in the consumer:

#nullable enable annotations
#nullable disable warnings

Set NullableReferenceTypes = false to omit both the directives and the reference-type ? annotations — useful for projects that disable nullable reference types or target older C# versions. Nullable value types (e.g. int? for an optional integer query parameter) are always emitted regardless of the setting:

var options = new HttpServiceClientGenerator.Options
{
    NullableReferenceTypes = false
};

Required value-type query parameters are appended to the query string unconditionally (rather than behind an always-true != null check), so the generated code is free of "expression is always true" warnings.

String enums

OpenAPI type: string enums are emitted as integer-backed C# enums (C# enums cannot be string-backed). Each member keeps its original wire value via a [System.Runtime.Serialization.EnumMember] attribute, and the enum is decorated with a string-enum converter matching the configured JsonSerializer (StringEnumConverter for Newtonsoft.Json, JsonStringEnumConverter for System.Text.Json) so values round-trip correctly. Values containing spaces or other invalid identifier characters are sanitized into valid PascalCase member names — e.g. "IN PROGRESS" becomes InProgress:

[Newtonsoft.Json.JsonConverter(typeof(Newtonsoft.Json.Converters.StringEnumConverter))]
public enum TaskStatus
{
    [System.Runtime.Serialization.EnumMember(Value = "IN PROGRESS")]
    InProgress = 0,
    [System.Runtime.Serialization.EnumMember(Value = "DONE")]
    DONE = 1
}

UriBuilderGenerator

Generates strongly-typed UriBuilder code from route definitions. This allows for type-safe URL construction based on defined API paths, supporting both fluent and flat API styles.

// Define routes manually or parse from OpenAPI
var routes = new List<UriBuilderGenerator.ApiRoute>
{
    new UriBuilderGenerator.ApiRoute { Path = "users/{userId:int}/orders" },
    new UriBuilderGenerator.ApiRoute { Path = "products/{category}/{id}" }
};

var options = new UriBuilderGenerator.Options
{
    UseFluentGeneration = true,
    FluentOptions = new UriBuilderGenerator.FluentGenerationOptions
    {
        UseNestedNamespaces = true,
        CollapseIdMethods = true
    }
};

var generator = new UriBuilderGenerator("MyNamespace", "MyApiRoutes", options);
string sourceCode = generator.Generate(routes);

ObjectExtensions

Extensions for converting runtime objects into their C# code initialization string representation. Useful for meta-programming and generating code that initializes objects with specific states.

// Simple types
int number = 42;
string numberCode = number.ToInitializerString(); // "42"

// Collections
var list = new List<string> { "A", "B" };
string listCode = list.ToInitializerString(); 
// "new List<string>() { "A", "B" }"

// Complex objects
var data = new { Id = 1, CreatedAt = DateTime.Now };
string objectCode = data.ToInitializerString();
// Generates object initialization syntax recursively