GlobalUsings¶

Emit global using directives as a complete source file with headers.

See also: Emit Overview | Types | Expressions | EmitOptions

Overview¶

Source generators often need to emit global using directives so generated code can use short type names. GlobalUsings.Emit() produces a fully-formed source file — with auto-generated header, license, and global using directives — and returns an OptionalEmit for integration with the standard emit pipeline.

var result = GlobalUsings.Emit(
    NamespaceRef.From("System.Text.Json"),
    NamespaceRef.From("Microsoft.Extensions.Logging"),
    NamespaceRef.From("System.Collections.Generic"));

if (result.IsValid(out var valid))
    context.AddSource("MyGenerator.GlobalUsings.g.cs", valid.Code);

Duplicate global usings

The C# compiler deduplicates global using directives across files, so it's safe if multiple generators emit the same namespace.

API¶

Emit with Default Options¶

// From strings
OptionalEmit result = GlobalUsings.Emit("System.Text.Json", "System.Linq");

// From NamespaceRef instances
OptionalEmit result = GlobalUsings.Emit(
    NamespaceRef.From("System.Text.Json"),
    NamespaceRef.From("System.Linq"));

Uses EmitOptions.Default — includes // <auto-generated/> header and license.

Emit with Custom Options¶

// Custom options
var options = EmitOptions.Default with { HeaderComment = "// My custom header" };

OptionalEmit result = GlobalUsings.Emit(options,
    NamespaceRef.From("System.Text.Json"),
    NamespaceRef.From("System.Collections.Generic"));

Static Usings¶

Use NamespaceRef.AsStatic() or the "static " prefix convention:

// Using NamespaceRef.AsStatic()
GlobalUsings.Emit(NamespaceRef.From("System.Math").AsStatic())

// Using string convention
GlobalUsings.Emit("static System.Math")

// Both produce: global using static System.Math;

Method Signatures¶

Method	Returns	Description
`Emit(params string[])`	`OptionalEmit`	Emit with default options from namespace strings
`Emit(params NamespaceRef[])`	`OptionalEmit`	Emit with default options from namespace refs
`Emit(EmitOptions, params string[])`	`OptionalEmit`	Emit with custom options from namespace strings
`Emit(EmitOptions, params NamespaceRef[])`	`OptionalEmit`	Emit with custom options from namespace refs

Generated Output¶

// <auto-generated/>
// SPDX-FileCopyrightText: 2024-present Deepstaging
// SPDX-License-Identifier: RPL-1.5
global using System.Text.Json;
global using System.Collections.Generic;
global using Microsoft.Extensions.Logging;

The output includes:

Header comment from EmitOptions.HeaderComment
License header from EmitOptions.LicenseHeader (if set)
Global using directives — one per namespace, with static keyword where specified

Source Generator Example¶

[Generator]
public class MyGenerator : IIncrementalGenerator
{
    public void Initialize(IncrementalGeneratorInitializationContext context)
    {
        context.RegisterPostInitializationOutput(ctx =>
        {
            var result = GlobalUsings.Emit(
                NamespaceRef.From("System.Text.Json"),
                NamespaceRef.From("System.Collections.Generic"),
                NamespaceRef.From("System.Threading.Tasks"),
                NamespaceRef.From("System.Linq"));

            if (result.IsValid(out var valid))
                ctx.AddSource("MyGenerator.GlobalUsings.g.cs", valid.Code);
        });
    }
}