+Mᐁ includes

devlooped · Jan 6, 2023 · 54d46c8 · 54d46c8
1 parent b661832
commit 54d46c8
Show file tree

Hide file tree

Showing 7 changed files with 348 additions and 7 deletions.
diff --git a/readme.md b/readme.md
@@ -27,27 +27,123 @@ 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)
 
 <!-- include src/ThisAssembly.AssemblyInfo/readme.md#content -->
+<!-- #content -->
+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)
+
+<!-- #content -->
+<!-- src/ThisAssembly.AssemblyInfo/readme.md#content -->
 
 ## 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)
 
 <!-- include src/ThisAssembly.Constants/readme.md#content -->
+<!-- #content -->
+This package generates a static `ThisAssembly.Constants` class with public
+constants for `@(Constant)` MSBuild items in the project.
+
+```xml
+  <ItemGroup>
+    <Constant Include="Foo.Bar" Value="Baz" Comment="Yay!" />
+    <Constant Include="Foo.Hello" Value="World" Comment="Comments make everything better 😍" />
+  </ItemGroup>
+```
+
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants.png)
+
+In addition to arbitrary constants via `<Constant ...>`, 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
+  <ItemGroup>
+    <FileConstant Include="@(Content)" />
+  </ItemGroup>
+```
+
+Which results in:
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants2.png)
+
+<!-- #content -->
+<!-- src/ThisAssembly.Constants/readme.md#content -->
 
 ## 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)
 
 <!-- include src/ThisAssembly.Metadata/readme.md#content -->
+<!-- #content -->
+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
+  <ItemGroup>
+    <AssemblyMetadata Include="Foo" Value="Bar" />
+  </ItemGroup>
+```
+
+<!-- #content -->
+<!-- src/ThisAssembly.Metadata/readme.md#content -->
 
 ## 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)
 
 <!-- include src/ThisAssembly.Project/readme.md#content -->
+<!-- #content -->
+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
+  <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" />
+  </ItemGroup>
+```
+
+![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Project.png)
+
+<!-- #content -->
+<!-- src/ThisAssembly.Project/readme.md#content -->
 
 ## ThisAssembly.Resources
 
@@ -58,13 +154,111 @@ This package generates a static `ThisAssembly.Resources` class with public
 properties exposing shortcuts to retrieve the contents of embedded resources.
 
 <!-- include src/ThisAssembly.Resources/readme.md#content -->
+<!-- #content -->
+
+This package generates a static `ThisAssembly.Resources` class with public 
+properties exposing typed APIs to retrieve the contents of embedded resources.
+
+
+```xml
+  <ItemGroup>
+    <EmbeddedResource Include="Content/Docs/License.md" />
+  </ItemGroup>
+```
+
+![](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
+  <PropertyGroup>
+    <EmbeddedResourceStringExtensions>.txt|.cs|.sql|.json|.md</EmbeddedResourceStringExtensions>
+  </PropertyGroup>
+```
+
+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).
+
+<!-- #content -->
+<!-- src/ThisAssembly.Resources/readme.md#content -->
 
 ## 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)
 
 <!-- include src/ThisAssembly.Strings/readme.md#content -->
+<!-- #content -->
+
+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
+        {
+            /// <summary>
+            /// For logging only!
+            /// => "Service {0} is required."
+            /// </summary>
+            public static string MissingService(object arg0)
+                => string.Format(CultureInfo.CurrentCulture, 
+                    Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("MissingService"), 
+                    arg0);
+        }
+
+        public static partial class Shopping
+        {
+            /// <summary>
+            /// => "We cannot ship {0} to {1}."
+            /// </summary>
+            public static string NoShipping(object arg0, object arg1)
+                => string.Format(CultureInfo.CurrentCulture, 
+                    Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("NoShipping"), 
+                    arg0, arg1);
+
+            /// <summary>
+            /// => "Product is out of stock at this time."
+            /// </summary>
+            public static string OutOfStock
+                => Strings.GetResourceManager("ThisStore.Properties.Resources").GetString("OutOfStock");
+        }
+    }
+}
+```
+
+<!-- #content -->
+<!-- src/ThisAssembly.Strings/readme.md#content -->
 
 # Dogfooding
 
@@ -81,4 +275,25 @@ The versioning scheme for packages is:
 - Branch builds: *42.42.42-*`[BRANCH]`.`[COMMITS]`
 
 
-<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+# Sponsors 
+
+<!-- sponsors.md -->
+[![Clarius Org](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/clarius.png "Clarius Org")](https://github.com/clarius)
+[![Christian Findlay](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MelbourneDeveloper.png "Christian Findlay")](https://github.com/MelbourneDeveloper)
+[![C. Augusto Proiete](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/augustoproiete.png "C. Augusto Proiete")](https://github.com/augustoproiete)
+[![Kirill Osenkov](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/KirillOsenkov.png "Kirill Osenkov")](https://github.com/KirillOsenkov)
+[![MFB Technologies, Inc.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MFB-Technologies-Inc.png "MFB Technologies, Inc.")](https://github.com/MFB-Technologies-Inc)
+[![SandRock](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/sandrock.png "SandRock")](https://github.com/sandrock)
+[![Eric C](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/eeseewy.png "Eric C")](https://github.com/eeseewy)
+[![Andy Gocke](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/agocke.png "Andy Gocke")](https://github.com/agocke)
+
+
+<!-- sponsors.md -->
+
+[![Sponsor this project](https://raw.githubusercontent.com/devlooped/sponsors/main/sponsor.png "Sponsor this project")](https://github.com/sponsors/devlooped)
+&nbsp;
+
+[Learn more about GitHub Sponsors](https://github.com/sponsors)
+
+<!-- https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.AssemblyInfo/readme.md b/src/ThisAssembly.AssemblyInfo/readme.md
@@ -20,3 +20,24 @@ on the `ThisAssembly.Info` class.
 
 <!-- #content -->
 <!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+# Sponsors 
+
+<!-- sponsors.md -->
+[![Clarius Org](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/clarius.png "Clarius Org")](https://github.com/clarius)
+[![Christian Findlay](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MelbourneDeveloper.png "Christian Findlay")](https://github.com/MelbourneDeveloper)
+[![C. Augusto Proiete](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/augustoproiete.png "C. Augusto Proiete")](https://github.com/augustoproiete)
+[![Kirill Osenkov](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/KirillOsenkov.png "Kirill Osenkov")](https://github.com/KirillOsenkov)
+[![MFB Technologies, Inc.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MFB-Technologies-Inc.png "MFB Technologies, Inc.")](https://github.com/MFB-Technologies-Inc)
+[![SandRock](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/sandrock.png "SandRock")](https://github.com/sandrock)
+[![Eric C](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/eeseewy.png "Eric C")](https://github.com/eeseewy)
+[![Andy Gocke](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/agocke.png "Andy Gocke")](https://github.com/agocke)
+
+
+<!-- sponsors.md -->
+
+[![Sponsor this project](https://raw.githubusercontent.com/devlooped/sponsors/main/sponsor.png "Sponsor this project")](https://github.com/sponsors/devlooped)
+&nbsp;
+
+[Learn more about GitHub Sponsors](https://github.com/sponsors)
+
+<!-- https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.Constants/readme.md b/src/ThisAssembly.Constants/readme.md
@@ -1,4 +1,4 @@
-<!-- #content -->
+<!-- #content -->
 This package generates a static `ThisAssembly.Constants` class with public
 constants for `@(Constant)` MSBuild items in the project.
 
@@ -26,4 +26,25 @@ Which results in:
 ![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants2.png)
 
 <!-- #content -->
-<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+# Sponsors 
+
+<!-- sponsors.md -->
+[![Clarius Org](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/clarius.png "Clarius Org")](https://github.com/clarius)
+[![Christian Findlay](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MelbourneDeveloper.png "Christian Findlay")](https://github.com/MelbourneDeveloper)
+[![C. Augusto Proiete](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/augustoproiete.png "C. Augusto Proiete")](https://github.com/augustoproiete)
+[![Kirill Osenkov](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/KirillOsenkov.png "Kirill Osenkov")](https://github.com/KirillOsenkov)
+[![MFB Technologies, Inc.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MFB-Technologies-Inc.png "MFB Technologies, Inc.")](https://github.com/MFB-Technologies-Inc)
+[![SandRock](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/sandrock.png "SandRock")](https://github.com/sandrock)
+[![Eric C](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/eeseewy.png "Eric C")](https://github.com/eeseewy)
+[![Andy Gocke](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/agocke.png "Andy Gocke")](https://github.com/agocke)
+
+
+<!-- sponsors.md -->
+
+[![Sponsor this project](https://raw.githubusercontent.com/devlooped/sponsors/main/sponsor.png "Sponsor this project")](https://github.com/sponsors/devlooped)
+&nbsp;
+
+[Learn more about GitHub Sponsors](https://github.com/sponsors)
+
+<!-- https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.Metadata/readme.md b/src/ThisAssembly.Metadata/readme.md
@@ -22,4 +22,25 @@ The metadata attribute can alternatively be declared using MSBuild syntax in the
 ```
 
 <!-- #content -->
-<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+# Sponsors 
+
+<!-- sponsors.md -->
+[![Clarius Org](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/clarius.png "Clarius Org")](https://github.com/clarius)
+[![Christian Findlay](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MelbourneDeveloper.png "Christian Findlay")](https://github.com/MelbourneDeveloper)
+[![C. Augusto Proiete](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/augustoproiete.png "C. Augusto Proiete")](https://github.com/augustoproiete)
+[![Kirill Osenkov](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/KirillOsenkov.png "Kirill Osenkov")](https://github.com/KirillOsenkov)
+[![MFB Technologies, Inc.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MFB-Technologies-Inc.png "MFB Technologies, Inc.")](https://github.com/MFB-Technologies-Inc)
+[![SandRock](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/sandrock.png "SandRock")](https://github.com/sandrock)
+[![Eric C](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/eeseewy.png "Eric C")](https://github.com/eeseewy)
+[![Andy Gocke](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/agocke.png "Andy Gocke")](https://github.com/agocke)
+
+
+<!-- sponsors.md -->
+
+[![Sponsor this project](https://raw.githubusercontent.com/devlooped/sponsors/main/sponsor.png "Sponsor this project")](https://github.com/sponsors/devlooped)
+&nbsp;
+
+[Learn more about GitHub Sponsors](https://github.com/sponsors)
+
+<!-- https://github.com/devlooped/sponsors/raw/main/footer.md -->
diff --git a/src/ThisAssembly.Project/readme.md b/src/ThisAssembly.Project/readme.md
@@ -17,4 +17,25 @@ them as `ProjectProperty` MSBuild items in the project file, such as:
 ![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Project.png)
 
 <!-- #content -->
-<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
+# Sponsors 
+
+<!-- sponsors.md -->
+[![Clarius Org](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/clarius.png "Clarius Org")](https://github.com/clarius)
+[![Christian Findlay](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MelbourneDeveloper.png "Christian Findlay")](https://github.com/MelbourneDeveloper)
+[![C. Augusto Proiete](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/augustoproiete.png "C. Augusto Proiete")](https://github.com/augustoproiete)
+[![Kirill Osenkov](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/KirillOsenkov.png "Kirill Osenkov")](https://github.com/KirillOsenkov)
+[![MFB Technologies, Inc.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MFB-Technologies-Inc.png "MFB Technologies, Inc.")](https://github.com/MFB-Technologies-Inc)
+[![SandRock](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/sandrock.png "SandRock")](https://github.com/sandrock)
+[![Eric C](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/eeseewy.png "Eric C")](https://github.com/eeseewy)
+[![Andy Gocke](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/agocke.png "Andy Gocke")](https://github.com/agocke)
+
+
+<!-- sponsors.md -->
+
+[![Sponsor this project](https://raw.githubusercontent.com/devlooped/sponsors/main/sponsor.png "Sponsor this project")](https://github.com/sponsors/devlooped)
+&nbsp;
+
+[Learn more about GitHub Sponsors](https://github.com/sponsors)
+
+<!-- https://github.com/devlooped/sponsors/raw/main/footer.md -->