ThisAssembly

ThisAssembly is a collection of Roslyn-powered source generators that expose project and assembly-level information as C# constants. The primary entry point is a partial class named ThisAssembly located in the global namespace (by default), which can be extended with manual members.

Key features:

• Exposes assembly attributes, Git information, MSBuild constants, and project metadata as type-safe C# constants.
• Uses the $(ThisAssemblyNamespace) MSBuild property to customize the root namespace.
• Each specialized package extends the ThisAssembly partial class to add its own nested types and members.
• For convenience, the ThisAssembly meta-package includes all individual packages.

// The generated class is partial, allowing you to add your own members
public partial class ThisAssembly
{
    public static void MyManualMethod() { }
}

The ThisAssembly.AssemblyInfo package automatically generates a static ThisAssembly.Info class for SDK-style projects. This class provides public constants that allow you to access assembly attributes directly in your code without using reflection.

By default, the following attributes are exposed as constants:

• AssemblyConfigurationAttribute
• AssemblyCompanyAttribute
• AssemblyTitleAttribute
• AssemblyDescriptionAttribute
• AssemblyProductAttribute
• AssemblyCopyrightAttribute
• AssemblyVersionAttribute
• AssemblyInformationalVersionAttribute
• AssemblyFileVersionAttribute

If your project already defines these attributes through other means (such as in your .csproj file), they will still be correctly emitted and accessible on the ThisAssembly.Info class.

The way ThisAssembly.Constants are exposed depends on the $(ThisAssemblyVisibility) setting:

1. Default (Internal): Uses const. This is optimal for performance as the compiler inlines values directly into the call site.
2. Public: Uses static readonly properties. This allows consuming code to use updated values from a referenced assembly without requiring a recompile.

// Default (Internal)
partial class ThisAssembly
{
    public partial class Constants
    {
        public const string Hello = "World";
    }
}

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

The ThisAssembly.Git package generates a static ThisAssembly.Git class containing constants for Git properties extracted from the current project. This allows you to embed versioning and source information directly into your application code.

Available properties include:

• Commit: The full commit hash.
• Sha: The first 9 characters of the commit hash.
• Root: The repository root path (normalized to forward slashes).
• Url: The repository URL (available if PublishRepositoryUrl is set to true).
• Branch: The current branch name, populated from CI environment variables (e.g., GitHub Actions, Azure DevOps, GitLab CI, etc.).

Note on CI Branches: When a CI system provides a pull request number, the Branch property is formatted as pr[NUMBER] (e.g., pr123), which is useful for semver metadata.

To automatically populate NuGet package metadata with Git information, use ThisAssembly.Git alongside Microsoft.SourceLink and NuGetizer.

For a GitHub repository, add the following package references to your project file. Note that for .NET 8 SDK and later, Microsoft.SourceLink is included by default and does not need to be added manually.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.SourceLink.GitHub" />
    <PackageReference Include="ThisAssembly.Git" />
    <PackageReference Include="NuGetizer" />
  </ItemGroup>
</Project>

The ThisAssembly.Metadata package provides a static class containing public constants that expose metadata defined in your project file. This allows you to access [System.Reflection.AssemblyMetadata] attributes as strongly-typed constants in your C# code instead of using reflection at runtime.

To make a piece of metadata available via this package, you must define it in your project file using MSBuild syntax with the <AssemblyMetadata> item.

<!-- In your .csproj file -->
<ItemGroup>
  <AssemblyMetadata Include="Foo" Value="Bar" />
</ItemGroup>

// In your C# code
string value = ThisAssembly.Metadata.Foo;
// value is "Bar"

The ThisAssembly.Project package automatically generates a static C# class named ThisAssembly.Project. This class contains public constants that expose MSBuild properties from your project file.

To include a property in the generated class, you must explicitly opt-in by adding it as a ProjectProperty item in your .csproj file. You can optionally provide a Comment attribute to customize the XML comment associated with the generated constant.

<PropertyGroup>
  <!-- Some arbitrary MSBuild property declared somewhere -->
  <Foo>Bar</Foo>
</PropertyGroup>

<ItemGroup>
  <!-- Opt-in to emitting that property value as a constant in ThisAssembly.Project -->
  <ProjectProperty Include="Foo" Comment="This comment replaces the default comment :)" />
</ItemGroup>

You can use CI packages produced from branches and pull requests to test builds as they are generated. The CI feed is available at https://pkg.kzu.app/index.json.

Package versions follow these schemes:

• PR builds: 42.42.42-pr[NUMBER]
• Branch builds: 42.42.42-[BRANCH].[COMMITS]

# Use the CI feed
https://pkg.kzu.app/index.json