From c05254bcce746134d1563738abe713b69c75c054 Mon Sep 17 00:00:00 2001 From: devlooped-bot Date: Wed, 4 Sep 2024 20:05:38 +0000 Subject: [PATCH] =?UTF-8?q?+M=E1=90=81=20includes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- readme.md | 308 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) diff --git a/readme.md b/readme.md index a712d5db..be6a1d79 100644 --- a/readme.md +++ b/readme.md @@ -28,6 +28,31 @@ all the other packages for convenience. [![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. + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.AssemblyInfo.png) + +Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the +generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. + + + ## ThisAssembly.Constants @@ -35,6 +60,38 @@ all the other packages for convenience. [![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. + +```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) + +Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the +generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. + + + ## ThisAssembly.Git @@ -42,6 +99,83 @@ all the other packages for convenience. [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Git.svg?color=green)](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) + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Git.png) + +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 + + + + + + + + +``` + +Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the +generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. + + + + ## ThisAssembly.Metadata @@ -49,6 +183,34 @@ all the other packages for convenience. [![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. + +![](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 + + + +``` + +Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the +generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. + + + ## ThisAssembly.Project @@ -56,6 +218,29 @@ all the other packages for convenience. [![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 the project file, such as: + +```xml + + + Bar + + + + + +``` + +![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Project.png) + +Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the +generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. + + + ## ThisAssembly.Resources @@ -66,6 +251,55 @@ 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 + + + +``` + +![](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 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. + +Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the +generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. + + + ## ThisAssembly.Strings @@ -73,6 +307,80 @@ properties exposing shortcuts to retrieve the contents of embedded resources. [![Downloads](https://img.shields.io/nuget/dt/ThisAssembly.Strings.svg?color=green)](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. + +![](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. | | +| 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)); + } + } +} +``` + +Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the +generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. + + + # Dogfooding