ThisAssembly.Constants 2.0.2

This project uses SponsorLink to attribute sponsor status (direct, indirect or implicit). For IDE usage, sponsor status is required. IDE-only warnings will be issued after a grace period otherwise.

This package generates a static ThisAssembly.Constants class with public constants for @(Constant) MSBuild items in the project.

  <ItemGroup>
    <Constant Include="Foo.Bar" Value="Baz" Comment="Yay!" />
    <Constant Include="Foo.Hello" Value="World" Comment="Comments make everything better 😍" />
  </ItemGroup>

These constants can use values from MSBuild properties, making compile-time values configurable via environment variables or command line arguments. For example:

  <PropertyGroup>
    <HttpDefaultTimeoutSeconds>10</HttpDefaultTimeoutSeconds>
  </PropertyGroup>
  <ItemGroup>
    <Constant Include="Http.TimeoutSeconds" 
              Value="$(HttpDefaultTimeoutSeconds)" 
              Type="int" 
              Comment="Default timeout in seconds for HTTP requests" />
  </ItemGroup>

The C# code could consume this constant as follows:

public HttpClient CreateHttpClient(string name, int? timeout = default)
{
    HttpClient client = httpClientFactory.CreateClient(name);
    client.Timeout = TimeSpan.FromSeconds(timeout ?? ThisAssembly.Constants.Http.TimeoutSeconds);
    return client;
}

Note how the constant is typed to int as specified in the Type attribute in MSBuild. The generated code uses the specified Type as-is, as well as the Value attribute in that case, so it's up to the user to ensure they match and result in valid C# code. For example, you can emit a boolean, long, double, etc.. If no type is provided, string is assumed. Values can also be multi-line and will use C# raw string literals if supported by the target language version (11+).

In this example, you could trivially change how your product behaves by setting the environment variable HttpDefaultTimeoutSeconds in CI. This is particularly useful for test projects, where you can easily change the behavior of the system under test without changing the code.

In addition to arbitrary constants via <Constant ...>, it's quite useful (in particular in test projects) to generate constants for files in the project, so there's also a shorthand for those:

  <ItemGroup>
    <FileConstant Include="@(Content)" />
  </ItemGroup>

Which results in:

Customizing the generated code

Set the $(ThisAssemblyNamespace) MSBuild property to set the namespace of the generated ThisAssembly root class. Otherwise, it will be generated in the global namespace.

The generated root ThisAssembly class is partial and has no visibility modifier by default, making it internal by default in C#.

You can set the $(ThisAssemblyVisibility) MSBuild property to public to make it public. This will also change all constants to be static readonly properties instead.

Default:

partial class ThisAssembly
{
    public partial class Constants
    {
        public const string Hello = "World";
    }
}

In this case, the compiler will inline the constants directly into the consuming code at the call site, which is optimal for performance for the common usage of constants.

Public:

public partial class ThisAssembly
{
    public partial class Constants
    {
        public static string Hello => "World";
    }
}

This makes it possible for consuming code to remain unchanged and not require a recompile when the the values of ThisAssembly are changed in a referenced assembly.

If you want to keep the properties as constants, you can instead extend the generated code by defining another partial that can modify its visibility as needed (or add new members).

// makes the generated class public
public partial ThisAssembly 
{
    // Nested classes are always public since the outer class 
    // already limits their visibility
    partial class Constants 
    {
        // add some custom constants
        public const string MyConstant = "This isn't configurable via MSBuild";

        // generated code will remain as constants
    }
}

Sponsors

Learn more about GitHub Sponsors