v5.12.9

- *Fixed:* Enable `text` specification to be used as-is by prefixing with a `+` plus-sign character.
- *Fixed:* Upgraded `DbEx` (`v2.5.8`) to include all related fixes and improvements.

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Represents the **NuGet** versions.
 
+## v5.12.9
+- *Fixed:* Enable `text` specification to be used as-is by prefixing with a `+` plus-sign character. 
+- *Fixed:* Upgraded `DbEx` (`v2.5.8`) to include all related fixes and improvements.
+
 ## v5.12.8
 - *Fixed*: Fixed the model code-generation by allowing the `ModelInherits` to be specified within the `Entity` YAML configuration to override the default.
 - *Fixed*: Fixed `dotnet run count` to exclude paths that start with `.` (dot) to avoid including hidden files in the count.

Common.targets

@@ -1,6 +1,6 @@
 <Project>
 	<PropertyGroup>
-		<Version>5.12.8</Version>
+		<Version>5.12.9</Version>
 		<LangVersion>preview</LangVersion>
 		<Authors>Avanade</Authors>
 		<Company>Avanade</Company>

docs/Entity-Const-Config.md

@@ -23,5 +23,5 @@ Property | Description
 -|-
 **`name`** | The unique constant name. [Mandatory]
 **`value`** | The .NET (C#) code for the constant value. [Mandatory]<br/>&dagger; The code generation will ensure the value is delimited properly to output correctly formed (delimited) .NET (C#) code.
-`text` | The overriding text for use in comments.<br/>&dagger; By default the `Text` will be the `Name` reformatted as sentence casing. It will be formatted as: `Represents a {text} constant value.` To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. `{{Xxx}}`).
+`text` | The overriding text for use in comments.<br/>&dagger; By default the `Text` will be the `Name` reformatted as sentence casing. It will be formatted as: `Represents a {text} constant value.` To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. `{{Xxx}}`). To have the text used as-is prefix with a `+` plus-sign character.
 

docs/Entity-Entity-Config.md

@@ -58,7 +58,7 @@ Provides the _key_ configuration.
 Property | Description
 -|-
 **`name`** | The unique entity name. [Mandatory]
-`text` | The overriding text for use in comments.<br/>&dagger; Overrides the Name (as sentence text) for the summary comments. It will be formatted as: `Represents the {Text} entity.`. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}).
+`text` | The overriding text for use in comments.<br/>&dagger; Overrides the Name (as sentence text) for the summary comments. It will be formatted as: `Represents the {Text} entity.`. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}). To have the text used as-is prefix with a `+` plus-sign character.
 `fileName` | The overriding file name.<br/>&dagger; Overrides the Name as the code-generated file name.
 `privateName` | The overriding private name.<br/>&dagger; Overrides the `Name` to be used for private fields. By default reformatted from `Name`; e.g. `FirstName` as `_firstName`.
 `argumentName` | The overriding argument name.<br/>&dagger; Overrides the `Name` to be used for argument parameters. By default reformatted from `Name`; e.g. `FirstName` as `firstName`.
@@ -280,7 +280,7 @@ Provides the data _Model_ configuration.
 Property | Description
 -|-
 `dataModel` | Indicates whether a data `model` version of the entity should also be generated (output to `.\Business\Data\Model`).<br/>&dagger; The model will be generated with `OmitEntityBase = true`. Any reference data properties will be defined using their `RefDataType` intrinsic `Type` versus their corresponding (actual) reference data `Type`.
-`modelInherits` | Overrides the default data `model` inherits value.
+`dataModelInherits` | Overrides the default data `model` inherits value.
 
 <br/>
 

docs/Entity-Operation-Config.md

@@ -66,13 +66,13 @@ Property | Description
 -|-
 **`name`** | The unique operation name. [Mandatory]
 **`type`** | The type of operation that is to be code-generated. Valid options are: `Get`, `GetColl`, `Create`, `Update`, `Patch`, `Delete`, `Custom`, `CustomManagerOnly`.<br/>&dagger; Defaults to `Custom`.
-`text` | The text for use in comments.<br/>&dagger; The `Text` will be defaulted for all the `Operation.Type` options with the exception of `Custom`. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}).
+`text` | The text for use in comments.<br/>&dagger; The `Text` will be defaulted for all the `Operation.Type` options with the exception of `Custom`. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}). To have the text used as-is prefix with a `+` plus-sign character.
 **`primaryKey`** | Indicates whether the properties marked as a primary key (`Property.PrimaryKey`) are to be used as the parameters.<br/>&dagger; This simplifies the specification of these properties as parameters versus having to declare each specifically. Each of the parameters will also be set to be mandatory.
 **`paging`** | Indicates whether a `PagingArgs` argument is to be added to the operation to enable (standardized) paging related logic.
 `valueType` | The .NET value parameter `Type` for the operation.<br/>&dagger; Defaults to the parent `Entity.Name` where the `Operation.Type` options are `Create` or `Update`.
 `returnType` | The .NET return `Type` for the operation.<br/>&dagger; Defaults to the parent `Entity.Name` where the `Operation.Type` options are `Get`, `GetColl`, `Create` or `Update`; otherwise, defaults to `void`.
 `returnTypeNullable` | Indicates whether the `ReturnType` is nullable for the operation.<br/>&dagger; This is only applicable for an `Operation.Type` of `Custom`. Will be inferred where the `ReturnType` is denoted as nullable; i.e. suffixed by a `?`.
-`returnText` | The text for use in comments to describe the `ReturnType`.<br/>&dagger; A default will be created where not specified. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}).
+`returnText` | The text for use in comments to describe the `ReturnType`.<br/>&dagger; A default will be created where not specified. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}). To have the text used as-is prefix with a `+` plus-sign character.
 `privateName` | The overriding private name.<br/>&dagger; Overrides the `Name` to be used for private usage. By default reformatted from `Name`; e.g. `GetByArgs` as `_getByArgs`.
 `withResult` | Indicates whether to use `CoreEx.Results` (aka Railway-oriented programming).<br/>&dagger; Defaults to `Entity.WilhResult`.
 

docs/Entity-Parameter-Config.md

@@ -38,7 +38,7 @@ Provides the _key_ configuration.
 Property | Description
 -|-
 **`name`** | The unique parameter name. [Mandatory]
-`text` | The overriding text for use in comments.<br/>&dagger; By default the `Text` will be the `Name` reformatted as sentence casing.
+`text` | The overriding text for use in comments.<br/>&dagger; By default the `Text` will be the `Name` reformatted as sentence casing. To have the text used as-is prefix with a `+` plus-sign character.
 **`type`** | The .NET `Type`.<br/>&dagger; Defaults to `string`. To reference a Reference Data `Type` always prefix with `RefDataNamespace` (e.g. `RefDataNamespace.Gender`) or shortcut `^` (e.g. `^Gender`). This will ensure that the appropriate Reference Data `using` statement is used. _Shortcut:_ Where the `Type` starts with (prefix) `RefDataNamespace.` or `^`, and the correspondong `RefDataType` attribute is not specified it will automatically default the `RefDataType` to `string.`
 **`nullable`** | Indicates whether the .NET Type should be declared as nullable; e.g. `int?`. Will be inferred where the `Type` is denoted as nullable; i.e. suffixed by a `?`. Where the .NET Type is not considered as an intrinsic type then will default to `true`.
 `default` | The C# code to default the value.<br/>&dagger; Where the `Type` is `string` then the specified default value will need to be delimited. Any valid value assignment C# code can be used.
@@ -94,7 +94,7 @@ Provides the _Web API_ configuration.
 Property | Description
 -|-
 `webApiFrom` | The option for how the parameter will be delcared within the Web API Controller. Valid options are: `FromQuery`, `FromBody`, `FromRoute`, `FromEntityProperties`.<br/>&dagger; Defaults to `FromQuery`; unless the parameter `Type` has also been defined as an `Entity` within the code-gen config file then it will default to `FromEntityProperties`. Specifies that the parameter will be declared with corresponding `FromQueryAttribute`, `FromBodyAttribute` or `FromRouteAttribute` for the Web API method. The `FromEntityProperties` will declare all properties of the `Entity` as query parameters.
-`webApiText` | The overriding text for use in the Web API comments.<br/>&dagger; By default the `Text` will be the `Name` reformatted as sentence casing.
+`webApiText` | The overriding text for use in the Web API comments.<br/>&dagger; By default the `WbeApiText` will be the `Name` reformatted as sentence casing. To have the text used as-is prefix with a `+` plus-sign character.
 
 <br/>
 

docs/Entity-Property-Config.md

@@ -49,8 +49,8 @@ Provides the _key_ configuration.
 Property | Description
 -|-
 **`name`** | The unique property name. [Mandatory]
-`text` | The overriding text for use in comments.<br/>&dagger; By default the `Text` will be the `Name` reformatted as sentence casing. Depending on whether the `Type` is `bool`, will appear in one of the two generated sentences. Where not `bool` it will be: Gets or sets a value indicating whether {text}.'. Otherwise, it will be: Gets or sets the {text}.'. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}).
-`modelText` | The overriding model text for use in comments.<br/>&dagger; By default the `ModelText` will be the `Name` reformatted as sentence casing. Depending on whether the `Type` is `bool`, will appear in one of the two generated sentences. Where not `bool` it will be: Gets or sets a value indicating whether {text}.'. Otherwise, it will be: Gets or sets the {text}.'. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}).
+`text` | The overriding text for use in comments.<br/>&dagger; By default the `Text` will be the `Name` reformatted as sentence casing. Depending on whether the `Type` is `bool`, will appear in one of the two generated sentences. Where not `bool` it will be: Gets or sets a value indicating whether {text}.'. Otherwise, it will be: Gets or sets the {text}.'. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}). To have the text used as-is prefix with a `+` plus-sign character.
+`modelText` | The overriding model text for use in comments.<br/>&dagger; By default the `ModelText` will be the `Name` reformatted as sentence casing. Depending on whether the `Type` is `bool`, will appear in one of the two generated sentences. Where not `bool` it will be: Gets or sets a value indicating whether {text}.'. Otherwise, it will be: Gets or sets the {text}.'. To create a `<see cref="XXX"/>` within use moustache shorthand (e.g. {{Xxx}}). To have the text used as-is prefix with a `+` plus-sign character.
 **`type`** | The .NET `Type`.<br/>&dagger; Defaults to `string`. To reference a Reference Data `Type` always prefix with `RefDataNamespace` (e.g. `RefDataNamespace.Gender`) or shortcut `^` (e.g. `^Gender`). This will ensure that the appropriate Reference Data `using` statement is used. _Shortcut:_ Where the `Type` starts with (prefix) `RefDataNamespace.` or `^`, and the correspondong `RefDataType` attribute is not specified it will automatically default the `RefDataType` to `string.`
 **`nullable`** | Indicates whether the .NET `Type` should be declared as nullable; e.g. `string?`. Will be inferred where the `Type` is denoted as nullable; i.e. suffixed by a `?`.
 `inherited` | Indicates whether the property is inherited and therefore should not be output within the generated Entity class.

samples/Demo/Beef.Demo.Api/Controllers/Generated/RobotController.cs

@@ -28,7 +28,7 @@ public RobotController(WebApi webApi, IRobotManager manager)
     partial void RobotControllerCtor(); // Enables additional functionality to be added to the constructor.
 
     /// <summary>
-    /// Gets the specified <see cref="Robot"/>.
+    /// Get the R-O-B-O-T.
     /// </summary>
     /// <param name="id">The <see cref="Robot"/> identifier.</param>
     /// <returns>The selected <see cref="Robot"/> where found.</returns>

samples/Demo/Beef.Demo.Business/Data/Generated/IRobotData.cs

@@ -13,7 +13,7 @@ namespace Beef.Demo.Business.Data;
 public partial interface IRobotData
 {
     /// <summary>
-    /// Gets the specified <see cref="Robot"/>.
+    /// Get the R-O-B-O-T.
     /// </summary>
     /// <param name="id">The <see cref="Robot"/> identifier.</param>
     /// <returns>The selected <see cref="Robot"/> where found.</returns>

samples/Demo/Beef.Demo.Business/DataSvc/Generated/IRobotDataSvc.cs

@@ -13,7 +13,7 @@ namespace Beef.Demo.Business.DataSvc;
 public partial interface IRobotDataSvc
 {
     /// <summary>
-    /// Gets the specified <see cref="Robot"/>.
+    /// Get the R-O-B-O-T.
     /// </summary>
     /// <param name="id">The <see cref="Robot"/> identifier.</param>
     /// <returns>The selected <see cref="Robot"/> where found.</returns>

samples/Demo/Beef.Demo.Business/Entities/Generated/ProductArgs.cs

@@ -8,15 +8,15 @@
 namespace Beef.Demo.Business.Entities;
 
 /// <summary>
-/// Represents the <see cref="Product"/> arguments entity.
+/// The <see cref="Product"/> arguments.
 /// </summary>
 public partial class ProductArgs : EntityBase
 {
     private string? _name;
     private string? _description;
 
     /// <summary>
-    /// Gets or sets the Name.
+    /// The product name.
     /// </summary>
     public string? Name { get => _name; set => SetValue(ref _name, value); }
 

samples/Demo/Beef.Demo.Business/Generated/IRobotManager.cs

@@ -13,7 +13,7 @@ namespace Beef.Demo.Business;
 public partial interface IRobotManager
 {
     /// <summary>
-    /// Gets the specified <see cref="Robot"/>.
+    /// Get the R-O-B-O-T.
     /// </summary>
     /// <param name="id">The <see cref="Robot"/> identifier.</param>
     /// <returns>The selected <see cref="Robot"/> where found.</returns>

samples/Demo/Beef.Demo.CodeGen/entity.beef-5.yaml

@@ -158,9 +158,9 @@ entities:
   # <Parameter Name="Args" Type="ProductArgs" Validator="ProductArgsValidator" />
   # </Operation>
   # </Entity>
-- { name: ProductArgs, text: '{{Product}} arguments', excludeAll: true,
+- { name: ProductArgs, text: '+The {{Product}} arguments.', excludeAll: true,
     properties: [
-      { name: Name, type: string },
+      { name: Name, type: string, text: +The product name. },
       { name: Description, type: string }
     ]
   }
@@ -177,7 +177,7 @@ entities:
       { name: ChangeLog, type: ChangeLog, isEntity: true, grpcFieldNo: 7 }
     ],
     operations: [
-      { name: Get, type: Get, primaryKey: true, webApiRoute: '{id}', grpc: true },
+      { name: Get, type: Get, primaryKey: true, webApiRoute: '{id}', grpc: true, text: +Get the R-O-B-O-T },
       { name: Create, type: Create, webApiLocation: ^Get, grpc: true },
       { name: Update, type: Update, primaryKey: true, webApiRoute: '{id}', grpc: true },
       { name: Patch, type: Patch, primaryKey: true, webApiRoute: '{id}' },

samples/Demo/Beef.Demo.Common/Agents/Generated/IRobotAgent.cs

@@ -26,7 +26,7 @@ namespace Beef.Demo.Common.Agents
     public partial interface IRobotAgent
     {
         /// <summary>
-        /// Gets the specified <see cref="Robot"/>.
+        /// Get the R-O-B-O-T.
         /// </summary>
         /// <param name="id">The <see cref="Robot"/> identifier.</param>
         /// <param name="requestOptions">The optional <see cref="HttpRequestOptions"/>.</param>

samples/Demo/Beef.Demo.Common/Entities/Generated/ProductArgs.cs

@@ -14,12 +14,12 @@
 namespace Beef.Demo.Common.Entities
 {
     /// <summary>
-    /// Represents the <see cref="Product"/> arguments entity.
+    /// The <see cref="Product"/> arguments.
     /// </summary>
     public partial class ProductArgs
     {
         /// <summary>
-        /// Gets or sets the Name.
+        /// The product name.
         /// </summary>
         public string? Name { get; set; }
 

templates/Beef.Template.Solution/content/.template.config/template.json

@@ -93,7 +93,7 @@
       "type": "generated",
       "generator": "constant",
       "parameters": {
-        "value": "5.12.8"
+        "value": "5.12.9"
       },
       "replaces": "BeefVersion"
     },

tools/Beef.CodeGen.Core/Beef.CodeGen.Core.csproj

@@ -32,7 +32,7 @@
 
   <ItemGroup>
     <PackageReference Include="OnRamp" Version="2.2.0" />
-    <PackageReference Include="DbEx" Version="2.5.7" />
+    <PackageReference Include="DbEx" Version="2.5.8" />
   </ItemGroup>
 
   <Import Project="..\..\Common.targets" />

tools/Beef.CodeGen.Core/Config/Entity/CodeGenConfig.cs

@@ -710,5 +710,37 @@ internal static void WarnWhereDeprecated(CodeGenConfig root, ConfigBase config,
                 }
             }
         }
+
+        /// <summary>
+        /// Gets the formatted text.
+        /// </summary>
+        /// <param name="text">The original text.</param>
+        /// <param name="formatter">The text formatter function.</param>
+        /// <returns>The formatted text.</returns>
+        /// <remarks>Where the text starts with a <c>+</c> (plus sign) then the text will be used as-is (without the plus); otherwise, the formatter will be used.</remarks>
+        internal static string? GetFormattedText(string? text, Func<string, string?> formatter)
+        {
+            text = text?.TrimEnd();
+            if (string.IsNullOrEmpty(text))
+                return text;
+
+            if (text.StartsWith('+'))
+                return text[1..];
+
+            return formatter(text);
+        }
+
+        /// <summary>
+        /// Gets the sentence text.
+        /// </summary>
+        /// <param name="text">The original text.</param>
+        /// <returns>The text with a terminating full stop.</returns>
+        internal static string? GetSentenceText(string? text)
+        {
+            if (string.IsNullOrEmpty(text))
+                return text;
+            else
+                return text.EndsWith('.') ? text : text + ".";
+        }
     }
 }

tools/Beef.CodeGen.Core/Config/Entity/ConstConfig.cs

@@ -48,13 +48,13 @@ public class ConstConfig : ConfigBase<CodeGenConfig, EntityConfig>
         /// </summary>
         [JsonPropertyName("text")]
         [CodeGenProperty("Key", Title = "The overriding text for use in comments.",
-            Description = "By default the `Text` will be the `Name` reformatted as sentence casing. It will be formatted as: `Represents a {text} constant value.` To create a `<see cref=\"XXX\"/>` within use moustache shorthand (e.g. `{{Xxx}}`).")]
+            Description = "By default the `Text` will be the `Name` reformatted as sentence casing. It will be formatted as: `Represents a {text} constant value.` To create a `<see cref=\"XXX\"/>` within use moustache shorthand (e.g. `{{Xxx}}`). To have the text used as-is prefix with a `+` plus-sign character.")]
         public string? Text { get; set; }
 
         /// <summary>
         /// Gets the formatted summary text.
         /// </summary>
-        public string? SummaryText => $"Represents a {Text} constant value.";
+        public string? SummaryText => CodeGenConfig.GetSentenceText(CodeGenConfig.GetFormattedText(Text, text => $"Represents a {text} constant value."));
 
         /// <summary>
         /// Gets the value formatted for code output.

tools/Beef.CodeGen.Core/Config/Entity/EntityConfig.cs

@@ -74,7 +74,7 @@ public class EntityConfig : ConfigBase<CodeGenConfig, CodeGenConfig>
         /// </summary>
         [JsonPropertyName("text")]
         [CodeGenProperty("Key", Title = "The overriding text for use in comments.",
-            Description = "Overrides the Name (as sentence text) for the summary comments. It will be formatted as: `Represents the {Text} entity.`. To create a `<see cref=\"XXX\"/>` within use moustache shorthand (e.g. {{Xxx}}).")]
+            Description = "Overrides the Name (as sentence text) for the summary comments. It will be formatted as: `Represents the {Text} entity.`. To create a `<see cref=\"XXX\"/>` within use moustache shorthand (e.g. {{Xxx}}). To have the text used as-is prefix with a `+` plus-sign character.")]
         public string? Text { get; set; }
 
         /// <summary>
@@ -1227,7 +1227,12 @@ public class EntityConfig : ConfigBase<CodeGenConfig, CodeGenConfig>
         /// <summary>
         /// Gets the formatted summary text.
         /// </summary>
-        public string? SummaryText => StringConverter.ToComments($"Represents the {Text} entity.");
+        public string? SummaryText => CodeGenConfig.GetSentenceText(StringConverter.ToComments(CodeGenConfig.GetFormattedText(Text, text => $"Represents the {text} entity.")));
+
+        /// <summary>
+        /// Gets the formatted model text.
+        /// </summary>
+        public string? ModelSummaryText => CodeGenConfig.GetSentenceText(StringConverter.ToComments(CodeGenConfig.GetFormattedText(Text, text => $"Represents the {text} model.")));
 
         /// <summary>
         /// Gets the entity name (accounts for <see cref="GenericWithT"/>).