Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devlooped/ThisAssembly
Exposes project and assembly level information as constants in the ThisAssembly class using source generators powered by Roslyn.
https://github.com/devlooped/ThisAssembly
csharp-sourcegenerator roslyn
Last synced: about 1 month ago
JSON representation
Exposes project and assembly level information as constants in the ThisAssembly class using source generators powered by Roslyn.
- Host: GitHub
- URL: https://github.com/devlooped/ThisAssembly
- Owner: devlooped
- License: mit
- Created: 2020-09-15T19:25:30.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-01T00:46:37.000Z (about 1 month ago)
- Last Synced: 2024-11-01T01:25:57.508Z (about 1 month ago)
- Topics: csharp-sourcegenerator, roslyn
- Language: C#
- Homepage: https://clarius.org/ThisAssembly
- Size: 1.55 MB
- Stars: 433
- Watchers: 8
- Forks: 23
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- License: license.txt
Awesome Lists containing this project
- RSCG_Examples - https://github.com/devlooped/ThisAssembly
README
 ThisAssembly
============
[](https://www.nuget.org/packages/ThisAssembly)
[](https://www.nuget.org/packages/ThisAssembly)
[](https://github.com//devlooped/ThisAssembly/blob/main/license.txt)
[](https://github.com/devlooped/ThisAssembly/actions)
*This project uses [SponsorLink](https://github.com/devlooped#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.*
Expose project and assembly level information as constants in the ThisAssembly
class using source generators powered by Roslyn.
The main generated entry point type is `ThisAssembly` in the global namespace (by default),
and is declared as partial so you can extend it too with manually created members.
> Use `$(ThisAssemblyNamespace)` MSBuild property to set a root namespace for `ThisAssembly`.
Each package in turn extends this partial class to add their own nestes types
and members.
The [ThisAssembly](https://nuget.org/packages/ThisAssembly) meta-package includes
all the other packages for convenience.
> For now, ThisAssembly only generates C# code.
## ThisAssembly.AssemblyInfo
[](https://www.nuget.org/packages/ThisAssembly.AssemblyInfo)
[](https://www.nuget.org/packages/ThisAssembly.AssemblyInfo)
This package generates a static `ThisAssembly.Info` class with public
constants exposing the following attribute values generated by default for SDK style projects:
* AssemblyConfigurationAttribute
* AssemblyCompanyAttribute
* AssemblyTitleAttribute
* AssemblyDescriptionAttribute
* AssemblyProductAttribute
* AssemblyCopyrightAttribute
* AssemblyVersionAttribute
* AssemblyInformationalVersionAttribute
* AssemblyFileVersionAttribute
If your project includes these attributes by other means, they will still be emitted properly
on the `ThisAssembly.Info` class.
## ThisAssembly.Constants
[](https://www.nuget.org/packages/ThisAssembly.Constants)
[](https://www.nuget.org/packages/ThisAssembly.Constants)
This package generates a static `ThisAssembly.Constants` class with public
constants for `@(Constant)` MSBuild items in the project.
```xml
```
These constants can use values from MSBuild properties, making compile-time values configurable
via environment variables or command line arguments. For example:
```xml
10
```
The C# code could consume this constant as follows:
```csharp
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](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/raw-string)
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 ``, 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:
```xml
```
Which results in:
## ThisAssembly.Git
[](https://www.nuget.org/packages/ThisAssembly.Git)
[](https://www.nuget.org/packages/ThisAssembly.Git)
This package generates a static `ThisAssembly.Git` class with constants
for the following Git properties from the current project:
* Commit
* Sha (first 9 chars from Commit)
* Root (normalized to forward slashes)
* Url (if PublishRepositoryUrl=true)
* Branch (from CI environment variables)
This package relies on your project's installed
[Microsoft.SourceLink.*](https://www.nuget.org/packages?q=Microsoft.SourceLink)
package reference according to your specific Git-based source control server
(such as GitHub, Azure DevOps, BitBucket, etc).
> NOTE: from .NET 8 SDK onwards, SourceLink is included by default, so you
> don't need to add it manually.
The `Branch` property is populated from environment variables provided
by the currently supported CI systems: GitHub Actions, Azure DevOps,
AppVeyor, TeamCity, Travis CI, Circle CI, GitLab CI, Buddy, and Jenkins.
Whenever the CI system provides a pull request number, the branch name is
`pr[NUMBER]`, such as `pr123`. This makes it easy to use it as a semver
metadata label.
> Note: by default, the values of these constants are populated during
"real" builds (that is, not IDE/design-time builds used to populate
intellisense). This is to avoid negatively affecting the editor's
performance. This means, however, that the properties will seem to
always be empty when inspecting them in the IDE (although never at
run-time). If you want to force population of these values for
design-time builds, set the `EnableSourceControlManagerQueries` property to `true`.
This property is defined and documented by
[dotnet/sourcelink](https://github.com/dotnet/sourcelink/blob/main/src/SourceLink.Common/build/Microsoft.SourceLink.Common.props#L14).
At the MSBuild level, targets can take a dependency on the provided
`InitializeGitInformation` target, which sets the equivalent properties
named:
* RepositoryCommit
* RepositorySha
* RepositoryRoot
* RepositoryUrl
* RepositoryBranch
The names of these properties were chosen on purpose to match the
properties used by [nuget pack](https://learn.microsoft.com/en-us/nuget/reference/msbuild-targets#pack-target)
and [nugetizer](https://github.com/devlooped/nugetizer) to populate
the relevant package metadata.
So if you have a GitHub repository, installing these three packages
will ensure you have the proper metadata out of the box and the simplest
packaging experience possible:
```xml
netstandard2.0
```
## ThisAssembly.Metadata
[](https://www.nuget.org/packages/ThisAssembly.Metadata)
[](https://www.nuget.org/packages/ThisAssembly.Metadata)
This package provides a static `ThisAssembly.Metadata` class with public
constants exposing each `[System.Reflection.AssemblyMetadata(..)]` defined in
the project file as [supported by the .NET SDK](https://learn.microsoft.com/en-us/dotnet/standard/assembly/set-attributes-project-file#set-arbitrary-attributes).
The metadata attribute is declared using MSBuild syntax in the project
(for .NET 5.0+ projects that have built-in support for `@(AssemblyMetadata)` items):
```xml
```
And a corresponding `ThisAssembly.Metadata.Foo` constant with the value `Bar` is provided
for this example.
## ThisAssembly.Project
[](https://www.nuget.org/packages/ThisAssembly.Project)
[](https://www.nuget.org/packages/ThisAssembly.Project)
This package generates a static `ThisAssembly.Project` class with public
constants exposing project properties that have been opted into this mechanism by adding
them as `ProjectProperty` MSBuild items in the project file, such as:
```xml
Bar
```
## ThisAssembly.Resources
[](https://www.nuget.org/packages/ThisAssembly.Resources)
[](https://www.nuget.org/packages/ThisAssembly.Resources)
This package generates a static `ThisAssembly.Resources` class with public
properties exposing shortcuts to retrieve the contents of embedded resources.
This package generates a static `ThisAssembly.Resources` class with public
properties exposing typed APIs to retrieve the contents of embedded resources.
```xml
```
Since markdown files are text files, the API will expose a `Text` property property
for it that will read its content once and cache it:
The `$(EmbeddedResourceStringExtensions)` MSBuild property allows customizing which
file extensions get treated as text files. By default, it's defined as:
```xml
.txt|.cs|.sql|.json|.md
```
You can append additional file extensions to this list, or override it completely.
The list must be pipe-separated.
You can always use the provided `GetStream` and `GetBytes` for more advanced scenarios (or for
non-text resources).
Optionally, you can specify the `Kind` metadata for a specific `EmbeddedResource` you want
treated as a text file:
```xml
```
You can also add a `Comment` item metadata attribute, which will be used as the `` XML
doc for the generated member.
## Customizing the generated code
The following MSBuild properties can be used to customize the generated code:
| Property | Description |
|-------------------------|------------------------------------------------------------------------------------------------------|
| ThisAssemblyNamespace | Sets the namespace of the generated `ThisAssembly` root class. If not set, it will be in the global namespace. |
| ThisAssemblyVisibility | Sets the visibility modifier of the generated `ThisAssembly` root class. If not set, it will be internal. |
## ThisAssembly.Strings
[](https://www.nuget.org/packages/ThisAssembly.Strings)
[](https://www.nuget.org/packages/ThisAssembly.Strings)
This package generates a static `ThisAssembly.Strings` class with public
constants exposing string resources in .resx files or methods with the right number of
parameters for strings that use formatting parameters.
In addition, it groups constants and methods in nested classes according to an optional
underscore separator to organize strings. For example, *User_InvalidCredentials* can be
accessed with *ThisAssembly.Strings.User.InvalidCredentials* if it contains a simple string,
or as a method with the right number of parametres if its value has a format string.
Given the following Resx file:
| Name | Value | Comment |
|-------------------------------|---------------------------------------|-------------------|
| Infrastructure_MissingService | Service {0} is required. | For logging only! |
| Shopping_NoShipping | We cannot ship {0} to {1}. | |
| Shopping_OutOfStock | Product is out of stock at this time. | |
| Shopping_AvailableOn | Product available on {date:yyyy-MM}. | |
The following code would be generated:
```csharp
partial class ThisAssembly
{
public static partial class Strings
{
public static partial class Infrastructure
{
///
/// For logging only!
/// => "Service {0} is required."
///
public static string MissingService(object arg0)
=> string.Format(CultureInfo.CurrentCulture,
Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("MissingService"),
arg0);
}
public static partial class Shopping
{
///
/// => "We cannot ship {0} to {1}."
///
public static string NoShipping(object arg0, object arg1)
=> string.Format(CultureInfo.CurrentCulture,
Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("NoShipping"),
arg0, arg1);
///
/// => "Product is out of stock at this time."
///
public static string OutOfStock
=> Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("OutOfStock");
///
/// Product available on {date:yyyy-MM}.
///
public static string AvailableOn(object date)
=> string.Format(CultureInfo.CurrentCulture,
Strings.GetResourceManager("ThisAssemblyTests.Resources").GetString("WithNamedFormat").Replace("{date:yyyy-MM}", "{0}"),
((IFormattable)date).ToString("yyyy-MM", CultureInfo.CurrentCulture));
}
}
}
```
## Customizing the generated code
The following MSBuild properties can be used to customize the generated code:
| Property | Description |
|-------------------------|------------------------------------------------------------------------------------------------------|
| ThisAssemblyNamespace | Sets the namespace of the generated `ThisAssembly` root class. If not set, it will be in the global namespace. |
| ThisAssemblyVisibility | Sets the visibility modifier of the generated `ThisAssembly` root class. If not set, it will be internal. |
## ThisAssembly.Vsix
[](https://www.nuget.org/packages/ThisAssembly.Vsix)
[](https://www.nuget.org/packages/ThisAssembly.Vsix)
Allows consuming VSIX manifest properties from code, as well as
MSBuild project properties from the VSIX manifest. For example:
And in the `source.extension.vsixmanifest`:
```xml
|%CurrentProject%;VsixDisplayName|
|%CurrentProject%;VsixDescription|
...
```
As shown above, in addition to making the [VSIX manifest metadata](https://learn.microsoft.com/en-us/visualstudio/extensibility/vsix-extension-schema-2-0-reference?view=vs-2022#metadata-element)
properties available as constants, the package also provides targets for those properties
with sensible defaults from project properties so that the manifest can leverage
[placeolder syntax](https://learn.microsoft.com/en-us/visualstudio/extensibility/vsix-extension-schema-2-0-reference?view=vs-2022#metadata-element)
and avoid duplication.
The available properties and their default values are:
| Name | Default Value |
|-------------------|-------------------------------------|
| VsixID | `$(PackageId)` or `$(AssemblyName)` |
| VsixVersion | `$(Version)` |
| VsixDisplayName | `$(Title)` |
| VsixDescription | `$(Description)` |
| VsixProduct | `$(Product)` |
| VsixPublisher | `$(Company)` |
| VsixLanguage | `$(NeutralLanguage)` or 'en-US' |
| VsixDescription | `$(Description)` |
As shown in the example above, the syntax for using these properties from the `source.extension.vsixmanifest` is
`|%CurrentProject%;[PROPERTY]|`. This is because the package defines a corresponding target to
retrieve each of the above properties. You can provide a different value for each property via
MSBuild as usual, of course.
Since the `$(PackageId)` property can be used as the VSIX ID, the `Pack` target is redefined to
mean `CreateVsixManifest`, so "packing" the VSIX is just a matter of right-clicking the VSIX
project and selecting "Pack".
## 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:
```csharp
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:
```csharp
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).
```csharp
// 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
}
}
```
# Dogfooding
[](https://pkg.kzu.io/index.json)
[](https://github.com/devlooped/ThisAssembly/actions)
We also produce CI packages from branches and pull requests so you can dogfood builds as quickly as they are produced.
The CI feed is `https://pkg.kzu.io/index.json`.
The versioning scheme for packages is:
- PR builds: *42.42.42-pr*`[NUMBER]`
- Branch builds: *42.42.42-*`[BRANCH]`.`[COMMITS]`
# Sponsors
[](https://github.com/clarius)
[](https://github.com/KirillOsenkov)
[](https://github.com/MFB-Technologies-Inc)
[](https://github.com/torutek-gh)
[](https://github.com/drivenet)
[](https://github.com/Keflon)
[](https://github.com/tbolon)
[](https://github.com/kfrancis)
[](https://github.com/twenzel)
[](https://github.com/unoplatform)
[](https://github.com/dansiegel)
[](https://github.com/rbnswartz)
[](https://github.com/jfoshee)
[](https://github.com/Mrxx99)
[](https://github.com/eajhnsn1)
[](https://github.com/IxTechnologies)
[](https://github.com/davidjenni)
[](https://github.com/Jonathan-Hickey)
[](https://github.com/akunzai)
[](https://github.com/jakobt)
[](https://github.com/tinohager)
[](https://github.com/ploeh)
[](https://github.com/KenBonny)
[](https://github.com/SimonCropp)
[](https://github.com/agileworks-eu)
[](https://github.com/sorahex)
[](https://github.com/arsdragonfly)
[](https://github.com/vezel-dev)
[](https://github.com/ChilliCream)
[](https://github.com/4OTC)
[](https://github.com/v-limo)
[](https://github.com/sponsors/devlooped)
[Learn more about GitHub Sponsors](https://github.com/sponsors)