From 733a16cc884f0fa8958b332f825b223226bc913f Mon Sep 17 00:00:00 2001
From: devlooped-bot <bot@devlooped.com>
Date: Fri, 27 Sep 2024 02:57:49 +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 | 80 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 57 insertions(+), 23 deletions(-)

diff --git a/readme.md b/readme.md
index 0e1cb619..7e0f57ce 100644
--- a/readme.md
+++ b/readme.md
@@ -54,9 +54,6 @@ 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.
-
 <!-- #assembly -->
 <!-- src/ThisAssembly.AssemblyInfo/readme.md#assembly -->
 
@@ -77,9 +74,47 @@ constants for `@(Constant)` MSBuild items in the project.
   </ItemGroup>
 ```
 
-
 ![](https://raw.githubusercontent.com/devlooped/ThisAssembly/main/img/ThisAssembly.Constants.png)
 
+These constants can use values from MSBuild properties, making compile-time values configurable 
+via environment variables or command line arguments. For example:
+
+```xml
+  <PropertyGroup>
+    <HttpDefaultTimeoutSeconds>10</HttpDefaultTimeoutSeconds>
+  </PropertyGroup>
+  <ItemGroup>
+    <Constant Include="Http.TimeoutSeconds" 
+              Value="$(HttpDefaultTimeoutSeconds)" 
+              Type="int" 
+              Comment="Default timeout in seconds for HTTP requests" />
+  </ItemGroup>
+```
+
+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., but a `DateTime` wouldn't be a valid constant even 
+if you set the `Value` to `DateTime.Now`. 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 `<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:
 
@@ -93,9 +128,6 @@ 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.
-
 <!-- #constants -->
 <!-- src/ThisAssembly.Constants/readme.md#constants -->
 
@@ -176,10 +208,6 @@ packaging experience possible:
 </Project>
 ```
 
-Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the 
-generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
-
-
 <!-- #git -->
 <!-- src/ThisAssembly.Git/readme.md#git -->
 
@@ -212,9 +240,6 @@ The metadata attribute can alternatively be declared using MSBuild syntax in the
   </ItemGroup>
 ```
 
-Set the `$(ThisAssemblyNamespace)` MSBuild property to set the root namespace of the 
-generated `ThisAssembly` class. Otherwise, it will be generated in the global namespace.
-
 <!-- #metadata -->
 <!-- src/ThisAssembly.Metadata/readme.md#metadata -->
 
@@ -242,9 +267,6 @@ them as `ProjectProperty` MSBuild items in the project file, such as:
 
 ![](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.
-
 <!-- #project -->
 <!-- src/ThisAssembly.Project/readme.md#project -->
 
@@ -301,9 +323,6 @@ treated as a text file:
 You can also add a `Comment` item metadata attribute, which will be used as the `<summary>` 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.
-
 <!-- #resources -->
 <!-- src/ThisAssembly.Resources/readme.md#resources -->
 
@@ -382,13 +401,28 @@ 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.
-
 <!-- #strings -->
 <!-- src/ThisAssembly.Strings/readme.md#strings -->
 
 <!-- include src/visibility.md -->
+## Customizing the generated class
+
+Set the `$(ThisAssemblyNamespace)` MSBuild property to set the namespace of the 
+generated `ThisAssembly` root class. Otherwise, it will be generated in the global namespace.
+
+All generated classes are partial and have no visibility modifier, so they can be extended 
+manually with another partial that can add members or modify their visibility to make them 
+public, if needed. The C# default for this case is for all classes to be internal.
+
+```csharp
+// makes the generated classes public
+public partial ThisAssembly 
+{
+    public partial class Constants { }
+}
+```
+
+<!-- src/visibility.md -->
 
 # Dogfooding