# πŸ‘‹ Your Sidekick for CodeDesignPlus.Net Microservices! πŸš€ Hey there, developer! πŸ‘‹ Tired of starting your microservices from scratch? Worry no more! The `generator-codedesignplus` is here to simplify and standardize the creation of your microservices based on the `CodeDesignPlus.Net.Microservice` archetype. Imagine having a tool that guides you step by step, generating the structure and key components of your microserviceβ€”all ready for you to focus on the business logic! 🀩 ## What's the Buzz About CodeDesignPlus.Net.Microservice? πŸ€” `CodeDesignPlus.Net.Microservice` is like your "starter kit" for building modern .NET microservices. It's a starting point that promotes separation of responsibilities, maintainability, and scalability. Forget tedious configurations, as it includes a well-defined project structure, default settings, and utility libraries. In short, it's the solid foundation you need to develop robust microservices quickly and efficiently. 😎 ## A Journey into the World of Domain-Driven Design (DDD) πŸ—ΊοΈ Before you start using the generator, it's important to know some key concepts of DDD: * **Domain:** It's the "world" of your software, the area of knowledge it operates on. Think of the domain as your business context with its own rules. For example, in an e-commerce platform, the domain might be "order management" or "product administration." * **Aggregate:** A cluster of entities treated as a unit, with a root entity acting as the "entry point." Aggregates are responsible for maintaining consistency within their boundaries. An order with its order lines is a good example. * **Entity:** An object with its own identity, persisting over time and having a defined lifecycle. Each entity has a unique identifier. A user with their name, email, and other details is an entity. * **Value Object:** An object without its own identity, defined by its attributes. They are immutable and compared by value. An address or a currency are perfect examples. * **Domain Event:** A notification of something that has happened in the domain. They are immutable and represent historical facts. Examples include "OrderCreated" or "UserRegistered." * **Repository:** A mechanism that "hides" access to persistent data. It provides an interface for your application to interact with the database without worrying about technical details. * **Command:** An intention to perform an action that changes the system's state. These are the orders you give, such as "CreateOrder" or "UpdateUser." * **Query:** A request to get information from the system without modifying anything. For example, "GetUserById" or "FindProductsByName." ## Configuration Flags: Customize Your Microservice! πŸ› οΈ | Flag | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--organization` | The name of your organizationβ€”the base of your namespace! | | `--microservice` | The name of your microserviceβ€”the heart of your project! | | `--description` | A detailed descriptionβ€”so everyone understands its purpose! | | `--contact-name` | The name of the contact personβ€”the one who always has the answers! | | `--contact-email` | The contact emailβ€”the way to communicate with the responsible person! | | `--vault` | The name of the vault for managing secretsβ€”your microservice's safe! | | `--is-crud` | Indicates whether your microservice will be a CRUDβ€”the easy path for data management! | | `--aggregate` | The name of the root aggregateβ€”the foundation of your domain! | | `--enable-grpc` | Enables the gRPC APIβ€”communication at the speed of light! | | `--enable-async-worker` | Enables an asynchronous workerβ€”for background tasks without stress! | | `--consumer-name` | The name of the event consumerβ€”the one who always keeps track of everything! | | `--consumer-aggregate` | The aggregate the consumer belongs toβ€”context is key! | | `--consumer-action` | The action to be performed by the consumer upon receiving an eventβ€”respond to the action! | | `--domain-events` | A comma-separated list of domain eventsβ€”your microservice's communication! | | `--entities` | A comma-separated list of entitiesβ€”objects with identity! | | `--commands` | A comma-separated list of commandsβ€”actions that change the system! | | `--queries` | A comma-separated list of queriesβ€”requests that fetch information! | | `--repository` | The name of the aggregate for which the repository is created or consultedβ€”access to your data! | | `--controller` | The name of the controllerβ€”the entry point to your microservice! | | `--proto-name` | The base name of the `.proto` fileβ€”the definition of your gRPC API! | | `--valueObjects` | A comma-separated list of value object namesβ€”objects without identity! | | `--dataTransferObject` | A comma-separated list of DTO namesβ€”the shape of the data as it travels! | ## Available Commands: Your Guide in Development! πŸš€ | Command | Description | Main Options | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `yo codedesignplus:microservice microservice` | Creates the base structure of a new microservice. Choose between a CRUD or custom pattern. | `--organization`, `--microservice`, `--description`, `--contact-name`, `--contact-email`, `--vault`, `--is-crud`, `--aggregate`, `--enable-grpc`, `--enable-async-worker`, `--consumer-name`, `--consumer-aggregate`, `--consumer-action`, `--domain-events`, `--entities`, `--commands`, `--queries` | | `yo codedesignplus:microservice aggregate` | Creates a new aggregate within an existing microservice. | `--organization`, `--microservice`, `--aggregate` | | `yo codedesignplus:microservice entity` | Creates one or more entities. | `--organization`, `--microservice`, `--entities` | | `yo codedesignplus:microservice valueObject` | Creates one or more value objects. | `--organization`, `--microservice`, `--valueObjects` | | `yo codedesignplus:microservice domainEvent`| Creates one or more domain events associated with an aggregate. | `--organization`, `--microservice`, `--aggregate`, `--domainEvents` | | `yo codedesignplus:microservice repository` | Creates a repository for a specific aggregate. | `--organization`, `--microservice`, `--repository` | | `yo codedesignplus:microservice controller` | Creates a controller to handle incoming requests. | `--organization`, `--microservice`, `--controller` | | `yo codedesignplus:microservice proto` | Creates a `.proto` file for a gRPC service. | `--organization`, `--microservice`, `--proto-name` | | `yo codedesignplus:microservice consumer` | Creates a consumer that reacts to domain events. | `--organization`, `--microservice`, `--consumer-name`, `--consumer-aggregate`, `--consumer-action` | | `yo codedesignplus:microservice query` | Creates one or more queries to retrieve data without modifying the state. | `--organization`, `--microservice`, `--aggregate`, `--repository`, `--queries` | | `yo codedesignplus:microservice command` | Creates one or more commands to perform actions that change the system state. | `--organization`, `--microservice`, `--aggregate`, `--repository`, `--commands` | | `yo codedesignplus:microservice dto` | Creates one or more Data Transfer Objects (DTOs) to transfer data. | `--organization`, `--microservice`, `--aggregate`, `--dataTransferObject` | | `yo codedesignplus:microservice grpc` | Creates a gRPC project. | `--organization`, `--microservice` | | `yo codedesignplus:microservice asyncWorker`| Creates an async worker project. | `--organization`, `--microservice` | ### 1. Creating a Microservice: The Beginning of It All! `yo codedesignplus:microservice microservice` This is the starting point for your new microservice. You can choose between a **CRUD** or **Custom** microservice, each with its own magic and design patterns. #### CRUD Microservice: Straight to the Point! A CRUD microservice focuses on managing data: create, read, update, and delete. It's ideal for scenarios where data persistence is the main concern. ```bash yo codedesignplus:microservice microservice \ --organization acme \ --microservice users \ --description "Microservice to manage platform users." \ --contact-name "Jane Doe" \ --contact-email "jane.doe@example.com" \ --vault vault-acme \ --is-crud \ --aggregate user \ --enable-grpc \ --enable-async-worker \ --consumer-name userRegistered \ --consumer-aggregate user \ --consumer-action send-welcome-email ``` **Note:** The REST entrypoint is created by default when creating a microservice. #### Custom Microservice: Maximum Flexibility! A custom microservice is for complex business logic and events, not just CRUD operations. It's perfect if the workflow is more important than data storage. ```bash yo codedesignplus:microservice microservice \ --organization acme \ --microservice inventory \ --description "Microservice to manage product inventory." \ --contact-name "John Smith" \ --contact-email "john.smith@example.com" \ --vault vault-acme \ --aggregate product \ --enable-grpc \ --enable-async-worker \ --consumer-name orderCreated \ --consumer-aggregate order \ --consumer-action update-stock \ --domain-events "ProductCreated,ProductUpdated,ProductRemoved" \ --entities Product,Category \ --commands CreateProduct,UpdateProduct,RemoveProduct \ --queries FindProductById,FindProductsByCategory ``` **Note:** The flags `--organization`, `--microservice`, `--description`, `--contact-name`, `--contact-email`, and `--vault` are optional after the initial creation, as they are stored in `archetype.json`. ### 2. Creating an Aggregate: Organizing Your Domain! `yo codedesignplus:microservice aggregate` Creates a new aggregate in your microservice. Aggregates are key in DDDβ€”they maintain the consistency of your entities! ```bash yo codedesignplus:microservice aggregate \ --organization acme \ --microservice users \ --aggregate UserProfile ``` ### 3. Creating an Entity: Giving Identity to Your Objects! `yo codedesignplus:microservice entity` Creates one or more entities. These are objects with identity that can change state! ```bash yo codedesignplus:microservice entity \ --organization acme \ --microservice inventory \ --entities Product,Category ``` ### 4. Creating a Value Object: Objects Without Identity! `yo codedesignplus:microservice valueObject` Creates one or more value objects. They are immutable and defined by their attributes! ```bash yo codedesignplus:microservice valueObject \ --organization acme \ --microservice users \ --valueObjects Email,Address ``` ### 5. Creating a Domain Event: Communicating What Happens! `yo codedesignplus:microservice domainEvent` Creates one or more domain events. These are representations of something that happened in your domain! ```bash yo codedesignplus:microservice domainEvent \ --organization acme \ --microservice orders \ --aggregate Order \ --domainEvents OrderCreated,OrderShipped ``` ### 6. Creating a Repository: Access to Your Data! `yo codedesignplus:microservice repository` Creates a repository for a specific aggregate. It's the interface to access persistent data! ```bash yo codedesignplus:microservice repository \ --organization acme \ --microservice products \ --repository Product ``` ### 7. Creating a Controller: Managing Requests! `yo codedesignplus:microservice controller` Creates a controller to manage incoming requests (HTTP or gRPC). ```bash yo codedesignplus:microservice controller \ --organization acme \ --microservice users \ --controller UserProfileController ``` ### 8. Creating a Proto: Defining Your gRPC API! `yo codedesignplus:microservice proto` Creates a `.proto` file for a gRPC service. It defines the messages and services for communication! ```bash yo codedesignplus:microservice proto \ --organization acme \ --microservice products \ --proto-name ProductService ``` ### 9. Creating an Event Consumer: Reacting to Changes! `yo codedesignplus:microservice consumer` Creates a consumer that reacts to events published by other microservices. ```bash yo codedesignplus:microservice consumer \ --organization acme \ --microservice notifications \ --consumer-name OrderCreated \ --consumer-aggregate Order \ --consumer-action send-order-confirmation ``` ### 10. Creating a Query: Getting Information Without Changing Anything! `yo codedesignplus:microservice query` Creates one or more queries to get information from the system without modifying its state! ```bash yo codedesignplus:microservice query \ --organization acme \ --microservice products \ --aggregate Product \ --repository Product \ --queries FindProductById,FindProductsByName ``` ### 11. Creating a Command: Changing the System State! `yo codedesignplus:microservice command` Creates one or more commands to perform actions that change the system's state. ```bash yo codedesignplus:microservice command \ --organization acme \ --microservice orders \ --aggregate Order \ --repository Order \ --commands CreateOrder,CancelOrder ``` ### 12. Creating Data Transfer Objects (DTOs): The Traveling Data! `yo codedesignplus:microservice dto` Creates one or more DTOs to transfer data between layers or microservices. ```bash yo codedesignplus:microservice dto \ --organization acme \ --microservice orders \ --aggregate Order \ --dataTransferObject OrderDto,OrderSummaryDto ``` ### 13. Creating a gRPC Project: Adding Fast Communication! `yo codedesignplus:microservice grpc` Creates a gRPC project within your microservice if you didn't do it initially! ```bash yo codedesignplus:microservice grpc \ --organization acme \ --microservice products ``` ### 14. Creating an Async Worker Project: Background Tasks! `yo codedesignplus:microservice asyncWorker` Creates an asynchronous worker project within your microservice for tasks that don't need to wait! ```bash yo codedesignplus:microservice asyncWorker \ --organization acme \ --microservice notifications ``` ## Internal Structure of the Generator and Contributions 🀝 ### How Does This Generator Work Internally? πŸ€” The `generator-codedesignplus` is built using Yeoman, a tool for creating code generators. Here's a summary of its structure: 1. **Entry Point (`index.mjs`):** * The "brain" of the generator. * Imports the `Core`, `Utils`, and `DotNet` classes from their respective files. * Retrieves command-line arguments (template, organization, microservice, etc.). * Executes methods to generate files, depending on the resource (aggregate, command, entity, etc.). 2. **`Core` Class (`core/core.mjs`):** * Manages arguments, options, and initial questions. * Maps generators to resources (aggregate, command, entity, etc.). * Displays help in the console. * Decides which generator to use, based on the template option. 3. **`Utils` Class (`core/utils.mjs`):** * Utility functions for the generator. * Reads and writes configuration information (`archetype.json`). * Transforms files (replaces names, namespaces, etc.). * Manages namespaces, adds `usings`, and generates files with `generateFiles`. 4. **`DotNet` Class (`core/dotnet.mjs`):** * Logic to perform operations related to .NET. * Removes projects from a microservice (executed when creating the microservice). 5. **Specific Generators (`core/*.mjs`):** * Generators for components (e.g., `aggregate.mjs`, `command.mjs`). * Define specific arguments and options. * Implement logic to generate files (using templates and `Utils`). 6. **Templates (`templates/`):** * Base files for generating code. * Placeholders (e.g., `CodeDesignPlus.Net.Microservice`, `Order`) are dynamically replaced. * The structure reflects a .NET project with the `CodeDesignPlus.Net.Microservice` archetype. 7. **Types (`types/`):** * Definitions of classes/interfaces for data type management within the generator. 8. **`package.json`:** * Project dependencies, development scripts, and package information. * Includes `yeoman-generator`, `find-up`, etc. ### How to Contribute to Development? 🀝 We love collaboration! If you want to contribute, follow these steps: 1. **Clone the repository:** ```bash git clone https://github.com/codedesignplus/generator-codedesignplus.git cd generator-codedesignplus ``` 2. **Install the dependencies:** ```bash npm install ``` 3. **Make your changes:** * Create a separate branch. * Modify files in `generators`, `templates`, and `types`. * Understand the logic (`index.mjs`, `core/core.mjs`, `core/utils.mjs`). * If you add templates, update the generators' logic. 4. **Run tests:** * Run tests with `npm test`. * Create or modify tests as needed. 5. **Ensure your code follows project style:** * Execute `npm run lint`, `npm run format` or `npm run prettier` 6. **Create a Pull Request:** * Upload your changes to your fork. * Create a pull request to the `main` branch. * Describe your changes clearly. ### Detailed File Structure πŸ“ Here's a summary of the generator's file structure: ``` generator-codedesignplus/ β”œβ”€β”€ generators/ # Generator logic β”‚ β”œβ”€β”€ core/ # Central logic β”‚ β”‚ β”œβ”€β”€ aggregate.mjs # Aggregate generator β”‚ β”‚ β”œβ”€β”€ appsettings.mjs # Appsettings generator β”‚ β”‚ β”œβ”€β”€ asyncWorker.mjs # Async Worker generator β”‚ β”‚ β”œβ”€β”€ command.mjs # Command generator β”‚ β”‚ β”œβ”€β”€ consumer.mjs # Consumer generator β”‚ β”‚ β”œβ”€β”€ controller.mjs # Controller generator β”‚ β”‚ β”œβ”€β”€ core.mjs # Core class β”‚ β”‚ β”œβ”€β”€ dataTransferObject.mjs # DTO generator β”‚ β”‚ β”œβ”€β”€ domainEvent.mjs # Domain event generator β”‚ β”‚ β”œβ”€β”€ dotnet.mjs # Utilities for .Net β”‚ β”‚ β”œβ”€β”€ entity.mjs # Entity generator β”‚ β”‚ β”œβ”€β”€ errors.mjs # Errors generator β”‚ β”‚ β”œβ”€β”€ grpc.mjs # gRPC generator β”‚ β”‚ β”œβ”€β”€ microservice.mjs # Microservice generator β”‚ β”‚ β”œβ”€β”€ proto.mjs # .proto file generator β”‚ β”‚ β”œβ”€β”€ query.mjs # Query generator β”‚ β”‚ β”œβ”€β”€ repository.mjs # Repository generator β”‚ β”‚ β”œβ”€β”€ utils.mjs # Utilities class β”‚ β”‚ β”œβ”€β”€ valueObject.mjs # Value object generator β”‚ β”‚ └── xml.mjs # XML Utilities β”‚ β”œβ”€β”€ index.mjs # Entry point β”‚ β”œβ”€β”€ templates/ # File templates β”‚ β”‚ β”œβ”€β”€ aggregate/ # Aggregate templates β”‚ β”‚ β”œβ”€β”€ command/ # Command templates β”‚ β”‚ β”œβ”€β”€ consumer/ # Consumer templates β”‚ β”‚ β”œβ”€β”€ controller/ # Controller templates β”‚ β”‚ β”œβ”€β”€ data-transfer-object/ # DTO templates β”‚ β”‚ β”œβ”€β”€ domain-event/ # Domain event templates β”‚ β”‚ β”œβ”€β”€ entity/ # Entity templates β”‚ β”‚ β”œβ”€β”€ errors/ # Errors templates β”‚ β”‚ β”œβ”€β”€ grpc/ # gRPC templates β”‚ β”‚ β”œβ”€β”€ microservice/ # Microservice templates β”‚ β”‚ β”œβ”€β”€ others/ # Other templates β”‚ β”‚ β”œβ”€β”€ query/ # Query templates β”‚ β”‚ β”œβ”€β”€ repository/ # Repository templates β”‚ β”‚ └── value-object/ # Value object templates β”‚ └── types/ # Type definitions β”‚ β”œβ”€β”€ aggregate.mjs β”‚ β”œβ”€β”€ appsettings.mjs β”‚ β”œβ”€β”€ base.mjs β”‚ β”œβ”€β”€ command.mjs β”‚ β”œβ”€β”€ consumer.mjs β”‚ β”œβ”€β”€ controller.mjs β”‚ β”œβ”€β”€ dataTransferObject.mjs β”‚ β”œβ”€β”€ domainEvents.mjs β”‚ β”œβ”€β”€ entity.mjs β”‚ β”œβ”€β”€ index.mjs β”‚ β”œβ”€β”€ proto.mjs β”‚ β”œβ”€β”€ query.mjs β”‚ β”œβ”€β”€ repository.mjs β”‚ └── valueObject.mjs β”œβ”€β”€ package.json # Project configuration └── README.md # This file ``` ## Usage πŸš€ 1. **Install Yeoman and the generator:** ```bash npm install -g yo npm install -g generator-codedesignplus ``` 2. **Run the commands:** Go to the folder where you want to generate the microservice and run one of the `yo codedesignplus:microservice` commands shown above. And that's it! We hope this generator is a great help to you on your journey as a microservice developer. If you have any questions, don't hesitate to contact us or create an issue in the repository! 😊