diff --git a/img/ThisAssembly.Resources.png b/img/ThisAssembly.Resources.png new file mode 100644 index 00000000..8e954e0f Binary files /dev/null and b/img/ThisAssembly.Resources.png differ diff --git a/img/ThisAssembly.Resources2.png b/img/ThisAssembly.Resources2.png new file mode 100644 index 00000000..f67b0fa1 Binary files /dev/null and b/img/ThisAssembly.Resources2.png differ diff --git a/readme.md b/readme.md index 61378bf7..c026f2e5 100644 --- a/readme.md +++ b/readme.md @@ -3,8 +3,8 @@ [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly) [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.svg?color=green)](https://www.nuget.org/packages/ThisAssembly) -[![License](https://img.shields.io/github/license/kzu/ThisAssembly.svg?color=blue)](https://github.com//kzu/ThisAssembly/blob/main/LICENSE) -[![Build](https://github.com/kzu/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/kzu/ThisAssembly/actions) +[![License](https://img.shields.io/github/license/devlooped/ThisAssembly.svg?color=blue)](https://github.com//devlooped/ThisAssembly/blob/main/LICENSE) +[![Build](https://github.com/devlooped/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/devlooped/ThisAssembly/actions) Exposes project and assembly level information as constants in the ThisAssembly @@ -13,106 +13,41 @@ class using source generators powered by Roslyn. The main generated entry point type is `ThisAssembly` in the global namespace, and is declared as partial so you can extend it too with manually created members. -Each package in turn extends this partial class too to add their own constants. +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. -> NOTE: as of .NET 5.0, only C# is supported for source generators. +> NOTE: for now, ThisAssembly only generates C# code. ## ThisAssembly.AssemblyInfo [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.AssemblyInfo.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.AssemblyInfo) [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.AssemblyInfo.svg?color=green)](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. - -![](img/ThisAssembly.AssemblyInfo.png) + ## ThisAssembly.Constants [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Constants.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Constants) [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Constants.svg?color=green)](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. - -![](img/ThisAssembly.Constants.png) - -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: - -![](img/ThisAssembly.Constants2.png) - + ## ThisAssembly.Metadata [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Metadata.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Metadata) [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Metadata.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Metadata) -This package provides a static `ThisAssembly.Metadata` class with public -constants exposing each `[System.Reflection.AssemblyMetadata(..)]` defined for -the project. - -![](img/ThisAssembly.Metadata.png) - -For an attribute declared (i.e. in *AssemblyInfo.cs*) like: - -```csharp - [assembly: System.Reflection.AssemblyMetadataAttribute("Foo", "Bar")] -``` - -A corresponding `ThisAssembly.Metadata.Foo` constant with the value `Bar` is provided. -The metadata attribute can alternatively be declared using MSBuild syntax in the project -(for .NET 5.0+ projects that have built-in support for `@(AssemblyMetadata)` items): - -```xml - - - -``` + ## ThisAssembly.Project [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Project.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Project) [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Project.svg?color=green)](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 project file, such as: - -```xml - - Bar - - - - -``` - -![](img/ThisAssembly.Project.png) + ## ThisAssembly.Resources @@ -122,82 +57,19 @@ them as `ProjectProperty` MSBuild items in project file, such as: This package generates a static `ThisAssembly.Resources` class with public properties exposing shortcuts to retrieve the contents of embedded resources. - -```xml - - - -``` - -![](img/ThisAssembly.Resources.png) + ## ThisAssembly.Strings [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Strings.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Strings) [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Strings.svg?color=green)](https://www.nuget.org/packages/ThisAssembly.Strings) -![](img/ThisAssembly.Strings.gif) - -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. | | - -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"); - } - } -} -``` + # Dogfooding [![CI Version](https://img.shields.io/endpoint?url=https://shields.kzu.io/vpre/Stunts/main&label=nuget.ci&color=brightgreen)](https://pkg.kzu.io/index.json) -[![Build](https://github.com/kzu/ThisAssembly/workflows/build/badge.svg?branch=main)](https://github.com/kzu/ThisAssembly/actions) +[![Build](https://github.com/devlooped/ThisAssembly/workflows/build/badge.svg?branch=main)](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. @@ -209,11 +81,4 @@ The versioning scheme for packages is: - Branch builds: *42.42.42-*`[BRANCH]`.`[COMMITS]` - -## Sponsors - -

-sponsors  by @clarius sponsors -

- -*[get mentioned here too](https://github.com/sponsors/devlooped)!* + \ No newline at end of file diff --git a/src/ThisAssembly.AssemblyInfo/readme.md b/src/ThisAssembly.AssemblyInfo/readme.md new file mode 100644 index 00000000..56c67146 --- /dev/null +++ b/src/ThisAssembly.AssemblyInfo/readme.md @@ -0,0 +1,22 @@ + +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. + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.AssemblyInfo.png) + + + diff --git a/src/ThisAssembly.Constants/readme.md b/src/ThisAssembly.Constants/readme.md new file mode 100644 index 00000000..e1b6ef3c --- /dev/null +++ b/src/ThisAssembly.Constants/readme.md @@ -0,0 +1,29 @@ + +This package generates a static `ThisAssembly.Constants` class with public +constants for `@(Constant)` MSBuild items in the project. + +```xml + + + + +``` + + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants.png) + +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: + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants2.png) + + + \ No newline at end of file diff --git a/src/ThisAssembly.Metadata/readme.md b/src/ThisAssembly.Metadata/readme.md new file mode 100644 index 00000000..da2588ed --- /dev/null +++ b/src/ThisAssembly.Metadata/readme.md @@ -0,0 +1,25 @@ + +This package provides a static `ThisAssembly.Metadata` class with public +constants exposing each `[System.Reflection.AssemblyMetadata(..)]` defined for +the project. + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Metadata.png) + +For an attribute declared (i.e. in *AssemblyInfo.cs*) like: + +```csharp +[assembly: System.Reflection.AssemblyMetadataAttribute("Foo", "Bar")] +``` + +A corresponding `ThisAssembly.Metadata.Foo` constant with the value `Bar` is provided. +The metadata attribute can alternatively be declared using MSBuild syntax in the project +(for .NET 5.0+ projects that have built-in support for `@(AssemblyMetadata)` items): + +```xml + + + +``` + + + \ No newline at end of file diff --git a/src/ThisAssembly.Project/readme.md b/src/ThisAssembly.Project/readme.md new file mode 100644 index 00000000..3b977b2e --- /dev/null +++ b/src/ThisAssembly.Project/readme.md @@ -0,0 +1,20 @@ + +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 + + + + + +``` + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Project.png) + + + \ No newline at end of file diff --git a/src/ThisAssembly.Resources/readme.md b/src/ThisAssembly.Resources/readme.md new file mode 100644 index 00000000..8e8310c3 --- /dev/null +++ b/src/ThisAssembly.Resources/readme.md @@ -0,0 +1,32 @@ + +This package generates a static `ThisAssembly.Resources` class with public +properties exposing typed APIs to retrieve the contents of embedded resources. + + +```xml + + + +``` + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Resources.png) + +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: + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Resources2.png) + +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 always use the provided `GetStream` and `GetBytes` for more advanced scenarios (or for +non-text resources). + + + \ No newline at end of file diff --git a/src/ThisAssembly.Strings/readme.md b/src/ThisAssembly.Strings/readme.md new file mode 100644 index 00000000..749203e4 --- /dev/null +++ b/src/ThisAssembly.Strings/readme.md @@ -0,0 +1,62 @@ + + +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. + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Strings.gif) + +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. | | + +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"); + } + } +} +``` + + + \ No newline at end of file