From 3a460a44c8dab02855f7ef6f569a52294aedfa5c Mon Sep 17 00:00:00 2001 From: Daniel Cazzulino Date: Wed, 4 Sep 2024 16:56:21 -0300 Subject: [PATCH] Aggregate individual package readmes into meta-package This involves not copying the readme to output (since includes should be relative to the source location, not the bin folder). Also renamed the anchors in each to avoid confusion. Expansion on the main readme should happen in the next automatic PR from include workflow. --- readme.md | 323 +----------------------- src/Directory.Build.targets | 2 + src/Directory.targets | 7 +- src/ThisAssembly.AssemblyInfo/readme.md | 4 +- src/ThisAssembly.Constants/readme.md | 4 +- src/ThisAssembly.Git/readme.md | 7 +- src/ThisAssembly.Metadata/readme.md | 4 +- src/ThisAssembly.Project/readme.md | 4 +- src/ThisAssembly.Resources/readme.md | 4 +- src/ThisAssembly.Strings/readme.md | 4 +- src/ThisAssembly/readme.md | 25 ++ 11 files changed, 57 insertions(+), 331 deletions(-) create mode 100644 src/ThisAssembly/readme.md diff --git a/readme.md b/readme.md index 7fe7a569..a712d5db 100644 --- a/readme.md +++ b/readme.md @@ -6,7 +6,7 @@ [![License](https://img.shields.io/github/license/devlooped/ThisAssembly.svg?color=blue)](https://github.com//devlooped/ThisAssembly/blob/main/license.txt) [![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 class using source generators powered by Roslyn. @@ -21,223 +21,41 @@ all the other packages for convenience. > [!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. - -![](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 [![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. - -```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 [![Version](https://img.shields.io/nuget/vpre/ThisAssembly.Git.svg?color=royalblue)](https://www.nuget.org/packages/ThisAssembly.Git) [![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). - -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 [![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. - -![](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 [![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 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 @@ -247,137 +65,14 @@ generated `ThisAssembly` class. Otherwise, it will be generated in the global na 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 [![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) - - - -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 diff --git a/src/Directory.Build.targets b/src/Directory.Build.targets index 20d7f0bf..afa32030 100644 --- a/src/Directory.Build.targets +++ b/src/Directory.Build.targets @@ -42,6 +42,7 @@ @@ -51,6 +52,7 @@ diff --git a/src/Directory.targets b/src/Directory.targets index 7e31a87f..ba7bdf8b 100644 --- a/src/Directory.targets +++ b/src/Directory.targets @@ -1,9 +1,10 @@ - - - + + + + diff --git a/src/ThisAssembly.AssemblyInfo/readme.md b/src/ThisAssembly.AssemblyInfo/readme.md index ad13703b..8589daec 100644 --- a/src/ThisAssembly.AssemblyInfo/readme.md +++ b/src/ThisAssembly.AssemblyInfo/readme.md @@ -1,4 +1,4 @@ - + This package generates a static `ThisAssembly.Info` class with public constants exposing the following attribute values generated by default for SDK style projects: @@ -21,6 +21,6 @@ on the `ThisAssembly.Info` class. Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. - + \ No newline at end of file diff --git a/src/ThisAssembly.Constants/readme.md b/src/ThisAssembly.Constants/readme.md index 176b84c0..b30f6589 100644 --- a/src/ThisAssembly.Constants/readme.md +++ b/src/ThisAssembly.Constants/readme.md @@ -1,4 +1,4 @@ - + This package generates a static `ThisAssembly.Constants` class with public constants for `@(Constant)` MSBuild items in the project. @@ -28,6 +28,6 @@ Which results in: Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. - + \ No newline at end of file diff --git a/src/ThisAssembly.Git/readme.md b/src/ThisAssembly.Git/readme.md index 5e03f505..52a65bff 100644 --- a/src/ThisAssembly.Git/readme.md +++ b/src/ThisAssembly.Git/readme.md @@ -1,4 +1,4 @@ - + This package generates a static `ThisAssembly.Git` class with constants for the following Git properties from the current project: @@ -15,6 +15,9 @@ This package relies on your project's installed 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. @@ -70,6 +73,6 @@ Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. - + \ No newline at end of file diff --git a/src/ThisAssembly.Metadata/readme.md b/src/ThisAssembly.Metadata/readme.md index 58ee19f7..0152f079 100644 --- a/src/ThisAssembly.Metadata/readme.md +++ b/src/ThisAssembly.Metadata/readme.md @@ -1,4 +1,4 @@ - + This package provides a static `ThisAssembly.Metadata` class with public constants exposing each `[System.Reflection.AssemblyMetadata(..)]` defined for the project. @@ -24,6 +24,6 @@ The metadata attribute can alternatively be declared using MSBuild syntax in the Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. - + \ No newline at end of file diff --git a/src/ThisAssembly.Project/readme.md b/src/ThisAssembly.Project/readme.md index 3ccbb2e8..95dad930 100644 --- a/src/ThisAssembly.Project/readme.md +++ b/src/ThisAssembly.Project/readme.md @@ -1,4 +1,4 @@ - + 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: @@ -19,6 +19,6 @@ them as `ProjectProperty` MSBuild items in the project file, such as: Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. - + \ No newline at end of file diff --git a/src/ThisAssembly.Resources/readme.md b/src/ThisAssembly.Resources/readme.md index 3f415837..4184fbab 100644 --- a/src/ThisAssembly.Resources/readme.md +++ b/src/ThisAssembly.Resources/readme.md @@ -1,4 +1,4 @@ - + This package generates a static `ThisAssembly.Resources` class with public properties exposing typed APIs to retrieve the contents of embedded resources. @@ -45,6 +45,6 @@ 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. - + \ No newline at end of file diff --git a/src/ThisAssembly.Strings/readme.md b/src/ThisAssembly.Strings/readme.md index 57d65aa7..4a30b382 100644 --- a/src/ThisAssembly.Strings/readme.md +++ b/src/ThisAssembly.Strings/readme.md @@ -1,4 +1,4 @@ - + This package generates a static `ThisAssembly.Strings` class with public constants exposing string resources in .resx files or methods with the right number of @@ -70,6 +70,6 @@ partial class ThisAssembly Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace. - + \ No newline at end of file diff --git a/src/ThisAssembly/readme.md b/src/ThisAssembly/readme.md new file mode 100644 index 00000000..d638afdd --- /dev/null +++ b/src/ThisAssembly/readme.md @@ -0,0 +1,25 @@ + + +## ThisAssembly.AssemblyInfo + + +## ThisAssembly.Constants + + +## ThisAssembly.Git + + +## ThisAssembly.Metadata + + +## ThisAssembly.Project + + +## ThisAssembly.Resources + + +## ThisAssembly.Strings + + + + \ No newline at end of file