Merge branch 'main' into docs/update-amplication-branch-info

Author: dericksozo

docs/plugins/before-after.md

@@ -7,7 +7,9 @@ slug: /plugins/plugin-events/plugin-events-before-after
 
 # Before and After Lifecycle Functions
 
-All events expose an identical interface with two functions that can be handled by the plugin and responsible for a different step in the lifecycle of the event. One for “before” the event is emitted and another for “after” the event is emitted.
+All events expose an identical interface with two functions that can be handled by the plugin and responsible for a different step in the lifecycle of the event. One for "before" the event is emitted and another for "after" the event is emitted.
+
+## Event Structure and Parameters
 
 ```tsx
 export interface PluginEventType<T extends EventParams> {
@@ -20,26 +22,48 @@ For each event, the type of `EventParams` is different, providing access to rele
 
 ```tsx
 export interface EventParams {}
+```
+
+## Before and After Function Signatures
 
+```tsx
 export type PluginBeforeEvent<T extends EventParams> = (
   dsgContext: DsgContext,
   eventParams: T
 ) => Promisable<T>;
 
+// Node.js [version](https://github.com/amplication/amplication/blob/master/libs/util/code-gen-types/src/plugins.types.ts#L21)
 export type PluginAfterEvent<T extends EventParams> = (
   dsgContext: DsgContext,
   eventParams: T,
   modules: ModuleMap
 ) => Promisable<ModuleMap>;
+
+// .NET [version](https://github.com/amplication/amplication/blob/master/libs/util/code-gen-types/src/dotnet-plugins.types.ts#L22)
+export type PluginAfterEvent<T extends EventParams, F> = (
+  dsgContext: DsgContext,
+  eventParams: T,
+  files: FileMap<F>
+) => Promisable<FileMap<F>>;
 ```
 
 In the `before` and `after` functions, we have an access to the context and the event params.
 The [context](docs\plugins\context.md) is used to gather common parts between events.
 The event params manipulate the default behavior by passing different values.
 
-In the `after` function, we also have access to the generated modules. An example of using this parameter is when you want to restructure the generated modules in a different folder structure.
+## Accessing and Modifying Generated Files
+
+In the `after` function, we also have access to the generated files. An example of using this parameter is when you want to restructure the generated files in a different folder structure.
+
+:::info
+In the `after` function for .NET plugins, we use a [`FileMap`](https://github.com/amplication/amplication/blob/master/libs/util/code-gen-types/src/files/file-map.ts). For Node.js plugins' `after` function we use a [`ModuleMap`](https://github.com/amplication/amplication/blob/master/libs/util/code-gen-types/src/code-gen-types.ts#L149).
+:::
+
+## Function Examples
+
+Most of the functions include examples. But, if you're looking for more comprehensive and real-world examples, you can explore the [code of the Amplication plugins](https://github.com/amplication/plugins/tree/master/plugins) directly. These plugins showcase various implementations and use cases for the before and after lifecycle functions.
 
-## Cautionary Guidelines
+## Best Practices and Cautions
 
 1. In the `after` function, avoid unintentionally overriding the entire generated file. Opt for smaller changes instead.
 2. In the `before` function, take care when modifying templates to not unintentionally affect code generation.

docs/plugins/dotnet-plugin-events/create-dtos.md

@@ -25,33 +25,24 @@ export interface CreateDTOsParams extends EventParams {
 }
 ```
 
-Example:
+### Example
 
 ```ts
-async afterCreateDTOs(
-  context: DsgContext,
-  eventParams: CreateDTOsParams,
-  modules: ModuleMap
-) {
-  const { entity, dtoName, dtoBasePath } = eventParams;
-  const dtoPath = join(dtoBasePath, `${dtoName}.cs`);
-  const dtoFile = modules.get(dtoPath);
-
+afterCreateDTOs(
+  context: dotnetTypes.DsgContext,
+  eventParams: dotnet.CreateDTOsParams,
+  files: FileMap<Class>
+): Promise<FileMap<Class>> {
+  const { entity, dtoName } = eventParams;
+  const dtoFile = files.get(`DTOs/${dtoName}.cs`);
   if (dtoFile) {
-    const updatedCode = dtoFile.code + `
-    public class ${entity.name}SummaryDTO
-    {
-        public int Id { get; set; }
-        public string Name { get; set; }
-    }
-    `;
-
-    modules.set({
-      path: dtoPath,
-      code: updatedCode
-    });
+    dtoFile.code.addProperty(
+      CsharpSupport.property({
+        name: "LastModified",
+        type: CsharpSupport.Types.dateTime(),
+      })
+    );
   }
-
-  return modules;
+  return files;
 }
 ```

docs/plugins/dotnet-plugin-events/create-entity-controller-base.md

@@ -35,30 +35,56 @@ An array of module actions available for the entity.
 
 An array of all entities in the application.
 
-Example:
+### Example
 
 ```ts
-async afterCreateEntityControllerBase(
-  context: DsgContext,
-  eventParams: CreateEntityControllerBaseParams,
-  modules: ModuleMap
-) {
-  const { resourceName, apisDir } = eventParams;
-  const controllerBasePath = join(apisDir, `${resourceName}ControllerBase.cs`);
-  const controllerBaseFile = modules.get(controllerBasePath);
+afterCreateEntityControllerBase(
+  context: dotnetTypes.DsgContext,
+  eventParams: dotnet.CreateEntityControllerBaseParams,
+  files: FileMap<Class>
+): Promise<FileMap<Class>> {
+  const { entity, resourceName, apisDir } = eventParams;
+  const controllerBasePath = `${apisDir}/${entity.name}/Base/${pascalCase(entity.name)}ControllerBase.cs`;
+  const controllerBaseFile = files.get(controllerBasePath);
 
   if (controllerBaseFile) {
-    const updatedCode = controllerBaseFile.code.replace(
-      "public abstract class",
-      "[ApiController]\n[Route(\"api/[controller]\")]\npublic abstract class"
+    // Add a protected method to the base controller
+    controllerBaseFile.code.addMethod(
+      CsharpSupport.method({
+        name: "ValidateEntityState",
+        access: "protected",
+        returnType: CsharpSupport.Types.boolean(),
+        parameters: [
+          CsharpSupport.parameter({
+            name: "entity",
+            type: CsharpSupport.Types.reference(entity.name),
+          }),
+        ],
+        body: `
+          if (entity == null)
+            return false;
+          
+          // Add custom validation logic here
+          return true;
+        `,
+      })
     );
 
-    modules.set({
-      path: controllerBasePath,
-      code: updatedCode
+    // Modify existing methods to use the new validation
+    const methods = controllerBaseFile.code.getMethods();
+    methods.forEach(method => {
+      if (method.name === `Create${entity.name}` || method.name === `Update${entity.name}`) {
+        const existingBody = method.body;
+        method.body = `
+          if (!ValidateEntityState(${camelCase(entity.name)}))
+            return BadRequest("Invalid entity state");
+          
+          ${existingBody}
+        `;
+      }
     });
   }
 
-  return modules;
+  return files;
 }
 ```

docs/plugins/dotnet-plugin-events/create-entity-controller.md

@@ -42,30 +42,45 @@ The directory where the API controllers are being generated.
 
 An object containing the CRUD actions available for the entity.
 
-Example:
+### Example
 
 ```ts
-async afterCreateEntityController(
-  context: DsgContext,
-  eventParams: CreateEntityControllerParams,
-  modules: ModuleMap
-) {
+afterCreateEntityController(
+  context: dotnetTypes.DsgContext,
+  eventParams: dotnet.CreateEntityControllerParams,
+  files: FileMap<Class>
+): Promise<FileMap<Class>> {
   const { entity, resourceName, apisDir } = eventParams;
-  const controllerPath = join(apisDir, `${resourceName}Controller.cs`);
-  const controllerFile = modules.get(controllerPath);
+  const controllerPath = `${apisDir}/${entity.name}/${pascalCase(entity.name)}Controller.cs`;
+  const controllerFile = files.get(controllerPath);
 
   if (controllerFile) {
-    const updatedCode = controllerFile.code.replace(
-      "public class",
-      "[ApiVersion(\"1.0\")]\npublic class"
+    // Add a custom action to the controller
+    controllerFile.code.addMethod(
+      CsharpSupport.method({
+        name: "ExportToCsv",
+        access: "public",
+        isAsync: true,
+        returnType: CsharpSupport.Types.task(CsharpSupport.Types.reference("IActionResult")),
+        decorators: [
+          CsharpSupport.decorator({
+            name: "HttpGet",
+            arguments: ["export-csv"],
+          }),
+        ],
+        body: `
+          var allItems = await _service.List();
+          var csv = ConvertToCsv(allItems);
+          return File(Encoding.UTF8.GetBytes(csv), "text/csv", "${entity.name}Export.csv");
+        `,
+      })
     );
 
-    modules.set({
-      path: controllerPath,
-      code: updatedCode
-    });
+    // Add necessary imports
+    controllerFile.code.addImport("System.Text");
+    controllerFile.code.addImport("Microsoft.AspNetCore.Mvc");
   }
 
-  return modules;
+  return files;
 }
 ```

docs/plugins/dotnet-plugin-events/create-entity-extensions.md

@@ -25,32 +25,63 @@ export interface CreateEntityExtensionsParams extends EventParams {
 }
 ```
 
-Example:
+### Example
 
 ```ts
-async afterCreateEntityExtensions(
-  context: DsgContext,
-  eventParams: CreateEntityExtensionsParams,
-  modules: ModuleMap
-) {
-  const { entity, apisDir } = eventParams;
-  const extensionsPath = join(apisDir, "Extensions", `${entity.name}Extensions.cs`);
-  const extensionsFile = modules.get(extensionsPath);
+afterCreateEntityExtensions(
+  context: dotnetTypes.DsgContext,
+  eventParams: dotnet.CreateEntityExtensionsParams,
+  files: FileMap<Class>
+): Promise<FileMap<Class>> {
+  const { entity, resourceName, apisDir } = eventParams;
+  const extensionsPath = `${apisDir}/${entity.name}/${pascalCase(entity.name)}Extensions.cs`;
+  const extensionsFile = files.get(extensionsPath);
 
   if (extensionsFile) {
-    const updatedCode = extensionsFile.code + `
-    public static string GetDisplayName(this ${entity.name} entity)
-    {
-        return $"{entity.FirstName} {entity.LastName}";
-    }
-    `;
-
-    modules.set({
-      path: extensionsPath,
-      code: updatedCode
-    });
+    // Add a custom extension method
+    extensionsFile.code.addMethod(
+      CsharpSupport.method({
+        name: "ToAuditString",
+        isStatic: true,
+        returnType: CsharpSupport.Types.string(),
+        parameters: [
+          CsharpSupport.parameter({
+            name: "this",
+            type: CsharpSupport.Types.reference(entity.name),
+            isThis: true,
+          }),
+        ],
+        body: `
+          return $"{entity.Id}|{entity.CreatedAt}|{entity.UpdatedAt}";
+        `,
+      })
+    );
+
+    // Add a custom mapper extension
+    extensionsFile.code.addMethod(
+      CsharpSupport.method({
+        name: "ToDto",
+        isStatic: true,
+        returnType: CsharpSupport.Types.reference(`${entity.name}Dto`),
+        parameters: [
+          CsharpSupport.parameter({
+            name: "this",
+            type: CsharpSupport.Types.reference(entity.name),
+            isThis: true,
+          }),
+        ],
+        body: `
+          return new ${entity.name}Dto
+          {
+            Id = entity.Id,
+            // Map other properties here
+            AuditString = entity.ToAuditString()
+          };
+        `,
+      })
+    );
   }
 
-  return modules;
+  return files;
 }
 ```

docs/plugins/dotnet-plugin-events/create-entity-interface.md

@@ -28,29 +28,24 @@ export interface CreateEntityInterfaceParams extends EventParams {
 }
 ```
 
-Example:
+### Example
 
 ```ts
-async afterCreateEntityInterface(
-  context: DsgContext,
-  eventParams: CreateEntityInterfaceParams,
-  modules: ModuleMap
-) {
-  const { entity, apisDir } = eventParams;
-  const interfacePath = join(apisDir, "Interfaces", `I${entity.name}.cs`);
-  const interfaceFile = modules.get(interfacePath);
-
+afterCreateEntityInterface(
+  context: dotnetTypes.DsgContext,
+  eventParams: dotnet.CreateEntityInterfaceParams,
+  files: FileMap<Interface>
+): Promise<FileMap<Interface>> {
+  const { entity } = eventParams;
+  const interfaceFile = files.get(`Interfaces/I${entity.name}.cs`);
   if (interfaceFile) {
-    const updatedCode = interfaceFile.code + `
-    Task<bool> IsUnique(string name);
-    `;
-
-    modules.set({
-      path: interfacePath,
-      code: updatedCode
-    });
+    interfaceFile.code.addMethod(
+      CsharpSupport.method({
+        name: "Validate",
+        returnType: CsharpSupport.Types.boolean(),
+      })
+    );
   }
-
-  return modules;
+  return files;
 }
 ```