Merge pull request #96 from neozhu/addcomments

Add Detailed Annotations to Code Templates for Better Understanding

src/Templatemap.cs

@@ -157,6 +157,8 @@ private static async Task<string> ReplaceTokensAsync(Project project, Intellisen
 					{ "rootnamespace", _defaultNamespace },
 					{ "namespace", ns },
 					{ "selectns", selectNs },
+					{ "author", "neozhu"},
+					{ "createddate", DateTime.Now.ToString("yyyy-MM-dd") },
 					{ "itemname", name },
 					{ "itemnamelowercase", name.ToLower() },
 					{ "nameofPlural", nameofPlural },

src/Templates/Caching/.cachekey.cs.txt

@@ -1,5 +1,20 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       Defines static methods and properties for managing cache keys and expiration 
+//       settings for {itemname}-related data. This includes creating unique cache keys for 
+//       various {itemnamelowercase} queries (such as getting all {itemnamelowercase}s, {itemnamelowercase}s by ID, etc.), 
+//       managing the cache expiration tokens to control cache validity, and providing a 
+//       mechanism to refresh cached data in a thread-safe manner.
+// </auto-generated>
+//------------------------------------------------------------------------------
 
 namespace {namespace};
 /// <summary>

src/Templates/Commands/AddEdit/.cs.txt

@@ -1,7 +1,28 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the command for adding or editing a {itemnamelowercase} entity,
+//       including validation and mapping operations. It handles domain events
+//       and cache invalidation for updated or newly created {itemnamelowercase}.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// This command can be used to add a new {itemnamelowercase} or edit an existing one.
+// It handles caching logic and domain event raising automatically.
+
 
-using {selectns}.{nameofPlural}.DTOs;
 using {selectns}.{nameofPlural}.Caching;
 using {selectns}.{nameofPlural}.Mappers;
 

src/Templates/Commands/AddEdit/.validator.cs.txt

@@ -1,5 +1,27 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the validation rules for the AddEdit{itemname}Command 
+//       used to add or edit {itemname} entities within the CleanArchitecture.Blazor 
+//       application. It enforces maximum field lengths and required properties 
+//       to maintain data integrity and validation standards.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// This validator enforces constraints on the AddEditContactCommand, such as
+// maximum field length for ...
 
 namespace {namespace};
 

src/Templates/Commands/Create/.cs.txt

@@ -1,5 +1,29 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the command and its handler for creating a new {itemname} entity
+//       within the CleanArchitecture.Blazor application. The command uses caching
+//       invalidation to ensure data consistency and raises domain events to maintain 
+//       the integrity of the entity lifecycle. It leverages Clean Architecture principles 
+//       for separation of concerns and encapsulation.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// This command can be used to create a new {itemnamelowercase} entity in the system. It includes
+// the required fields for the {itemnamelowercase} and automatically raises necessary domain
+// events for integration with other bounded contexts in the application.
 
 using {selectns}.{nameofPlural}.Caching;
 using {selectns}.{nameofPlural}.Mappers;

src/Templates/Commands/Create/.validator.cs.txt

@@ -1,5 +1,28 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the validation rules for the Create{itemname}Command, 
+//       used to create {itemname} entities within the CleanArchitecture.Blazor 
+//       application. It ensures that essential fields are validated correctly, 
+//       including maximum lengths and mandatory requirements for required fields.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// This validator is used to ensure that a Create{itemname}Command meets the required
+// validation criteria. It enforces constraints like maximum field lengths and 
+// ensures that the Name field is not empty before proceeding with the command execution.
 
 namespace {namespace};
 

src/Templates/Commands/Delete/.cs.txt

@@ -1,5 +1,30 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the command and its handler for deleting one or more
+//       {itemname} entities from the CleanArchitecture.Blazor application. It
+//       implements caching invalidation logic to ensure that data consistency is
+//       maintained. Domain events are triggered for deleted entities to support 
+//       integration with other parts of the system.
+//       for separation of concerns and encapsulation.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// This command can be used to delete multiple {nameofPlural} from the system by specifying
+// their IDs. The handler also raises domain events for each deleted {itemnamelowercase} to
+// notify other bounded contexts and invalidate relevant cache entries.
 
 using {selectns}.{nameofPlural}.Caching;
 

src/Templates/Commands/Delete/.validator.cs.txt

@@ -1,5 +1,28 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the validation rules for the Delete{itemname}Command used
+//       to delete {itemname} entities within the CleanArchitecture.Blazor application. 
+//       It ensures that the command has valid input, particularly verifying that the 
+//       list of {itemnamelowercase} IDs to delete is not null and contains only positive IDs.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// This validator ensures that the Delete{itemname}Command is valid before attempting 
+// to delete {itemnamelowercase} records from the system. It verifies that the ID list is not 
+// null and that all IDs are greater than zero.
 
 namespace {namespace};
 

src/Templates/Commands/Import/.cs.txt

@@ -1,5 +1,30 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the command, handler, and associated logic for importing 
+//       {itemnamelowercase}s from an Excel file into the CleanArchitecture.Blazor application. 
+//       The import process supports validating data and ensuring no duplicates are 
+//       inserted. Additionally, a command for creating a {itemnamelowercase} template file is provided 
+//       to facilitate bulk data entry for end users.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// - Use `Import{itemname}sCommand` to import {itemnamelowercase}s from an Excel file, ensuring proper validation
+//   and avoiding duplicates.
+// - Use `Create{itemname}sTemplateCommand` to generate an Excel template for entering {itemnamelowercase} data 
+//   that can be later imported using the import command.
 
 using {selectns}.{nameofPlural}.DTOs;
 using {selectns}.{nameofPlural}.Caching;

src/Templates/Commands/Import/.validator.cs.txt

@@ -1,5 +1,28 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the validation rules for the Import{itemname}sCommand 
+//       within the CleanArchitecture.Blazor application. It ensures that the 
+//       command's required properties are correctly set before proceeding with 
+//       the {itemnamelowercase} import process.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// This validator is used to ensure that an Import{itemname}sCommand has valid input 
+// before attempting to import {itemnamelowercase} data. It checks that the Data property is not 
+// null and is not empty, ensuring that the command has valid content for import.
 
 namespace {namespace};
 

src/Templates/Commands/Update/.cs.txt

@@ -1,5 +1,29 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the Update{itemname}Command and its handler for updating 
+//       an existing {itemname} entity within the CleanArchitecture.Blazor application. 
+//       It includes caching invalidation logic to maintain data consistency and 
+//       raises a domain event upon successful update to notify other parts of the system.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// Use `Update{itemname}Command` to update an existing {itemnamelowercase} entity in the system. 
+// The handler ensures that if the entity is found, the changes are applied and 
+// the necessary domain event (`{itemname}UpdatedEvent`) is raised. Caching is also 
+// invalidated to keep the {itemnamelowercase} list consistent.
 
 using {selectns}.{nameofPlural}.Caching;
 using {selectns}.{nameofPlural}.Mappers;

src/Templates/Commands/Update/.validator.cs.txt

@@ -1,5 +1,31 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the validation rules for the Update{itemname}Command within 
+//       the CleanArchitecture.Blazor application. It ensures that the command has 
+//       all required fields properly populated and validates constraints such as 
+//       maximum length and non-null requirements before proceeding with updating 
+//       a {itemnamelowercase}.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// The `Update{itemname}CommandValidator` is used to validate that an `Update{itemname}Command` 
+// contains valid and complete data before processing the update. It enforces rules such as 
+// ensuring that the `Id` is provided, the `Name` is not empty, and certain properties 
+// (e.g., ...) do not exceed their maximum 
+// allowed length.
 
 namespace {namespace};
 

src/Templates/DTOs/.dto.cs.txt

@@ -1,5 +1,30 @@
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
+//------------------------------------------------------------------------------
+// <auto-generated>
+//     This file is part of the CleanArchitecture.Blazor project.
+//     Licensed to the .NET Foundation under one or more agreements.
+//     The .NET Foundation licenses this file to you under the MIT license.
+//     See the LICENSE file in the project root for more information.
+//
+//     Author: {author}
+//     Created Date: {createddate}
+//     Last Modified: {createddate}
+//     Description: 
+//       This file defines the Data Transfer Object (DTO) for the {itemname} entity 
+//       used within the CleanArchitecture.Blazor application. The {itemname}Dto is 
+//       responsible for transferring data between layers while maintaining the 
+//       structure and format required by application features like commands, queries, 
+//       and views.
+//     
+//     Documentation:
+//       https://docs.cleanarchitectureblazor.com/features/{itemnamelowercase}
+// </auto-generated>
+//------------------------------------------------------------------------------
+
+// Usage:
+// The `{itemname}Dto` class is used to represent {itemnamelowercase} data throughout the CleanArchitecture.Blazor
+// application, providing a well-defined contract for passing {itemnamelowercase} information between different 
+// layers and services. Each property includes a description for better understandability during 
+// serialization and documentation generation.
 
 namespace {namespace};