Blazor For Kids

Understanding the Generated Types and Methods

Sample Entity Declaration

To use the generated types and methods correctly and safely, there are several important concepts and behaviors you should understand. These rules are designed to help you maintain a clean and maintainable architecture, especially when your application grows.

1. Entity configuration must be done only inside the BkConfiguration method of the partial class for each entity. This method is located in your own code, inside the partial entity definition. You should not try to configure the entity elsewhere.
2. Generated code updates automatically. Every time you make a change to your partial entity class (e.g., add or remove properties), the framework will regenerate the corresponding code to reflect that change. This ensures that your entity stays in sync with its model and underlying logic.
3. New properties are automatically mirrored. When you add a new property to your entity, the same property will be added to the generated partial entity class and to the generated EntityModel, using the same name and type.
4. Generated properties in the entity are immutable by design. This means you cannot change their values directly. This is intentional and helps enforce a clean domain model. Any changes or logic that affect the entity must be declared in the entity itself — not scattered across the application. This makes it much easier to reason about your codebase and perform maintenance in the future.
5. The generated EntityModel (named by convention {EntityName}Model) acts as a bridge between the UI and the entity itself. It has public setters for all properties so you can bind and modify data in forms. But remember — it's just a transport layer, not the real domain logic.
6. The EntityModel includes two key methods: Create() and Update(). These methods are responsible for transforming the model into a real entity or updating an existing one. On the entity side, there are also corresponding Create and Update methods which the model uses under the hood. These are tightly coupled and designed to work together — do not bypass them.
   
7. Non-editable (functional) properties are managed automatically by the framework. You don't need to bind them in the UI or pass them to Create or Update methods. These might include timestamps, versioning fields, user tracking, etc.
8. You can add custom methods inside the entity class if you need to perform logic that’s not handled through the EntityModel. For example, if you need to update only one property based on a complex rule, you can create a method in the entity and call it when using the DbContext.
   
9. If you implement custom editing logic (outside of Create/Update), it is your responsibility to validate the entity before saving. You must call the entity's IsValid() method before calling SaveChanges. If you skip this, invalid entities may be saved to the database.
   
10. If you bypass the generated Create, Update, or Delete methods, you are also responsible for publishing the correct events. These events are essential for triggering any registered event handlers (such as those for caching, syncing, or audit logs). If you skip publishing them, none of the automation will happen — and your system may become inconsistent.
    
11. If you use the default caching system, you must set the CacheKey in your custom edit methods. Otherwise, the framework will not be able to invalidate the cache after changes, and your UI may show outdated data.
    

Summary

BlazorForKids provides a robust and safe foundation for working with entities, models, and the database — but it's important to understand how the generated code works and what your responsibilities are when you step outside of the default paths.

The system is designed to centralize business logic inside the entity itself and provide clean communication between the UI and the backend via the EntityModel. When you follow this pattern, your code will be easier to maintain, debug, and extend.

Below is a full example showing:

Sample: The generated partial entity

• Note: The framework automatically applies essential attributes such as [Required], [StringLength], and [Display] to your properties based on the configuration you define in BkConfiguration. You don’t need to add them manually.
• Note: The framework also generates the necessary Entity Type Configuration for EF Core behind the scenes, so you don’t need to manually configure entity mapping, relationships, or constraints.
• Note: The parameters included in the generated Create and Update methods are only the ones that are actually required to construct or update the entity. Optional and framework-managed properties are excluded automatically.

Sample: The generated entity model

• Note: The EntityModel includes only the properties that are necessary for mapping data to and from the actual entity. It is designed to mirror the entity’s structure while keeping the focus on editable fields.
• Note: In addition to data properties, the EntityModel also includes metadata used by the framework to generate the appropriate UI editors (such as labels, tooltips, placeholders, and validation rules).
• Note: The EntityModel provides helper methods such as Clone() and mappings like Create() or Update(), which simplify UI-to-entity transformations and are commonly used when working with forms and temporary copies.

Using Generated Methods in a Custom Service

The following EmployeeService class is provided as an example to demonstrate how you can work with the generated types and methods in BlazorForKids. While you are free to implement services like this in your own projects, you do not need to create a custom service manually to perform basic CRUD operations — the framework already provides built-in functionality for creating, updating, deleting, and querying entities.

This example is meant to show how the EntityModel, validation methods, and the mediator-based query system can be used in a real-world service class. It also illustrates best practices such as:

• How to call the Create() and Update() methods of the EntityModel.
• How to validate entities using the IsValid() method before saving changes.
• How to work with the ApplyChangesWithResultAsync() extension to persist data and return a result object.
• How to filter and paginate query results using BkFilterCollection.

Notes:

• Validation: Every time you create or update an entity manually, you must call the IsValid() method. This ensures that all validation rules defined in your entity are checked before attempting to save. If you skip this step, the entity could be saved in an invalid state.
• Event Handling: The ApplyChangesWithResultAsync() method also handles publishing any required domain events (such as when caching or event listeners are involved). This helps maintain consistency and ensures side effects are triggered as expected.
• Queries: The method GetEmployeesAsync() demonstrates how to use IBkMediatorDomain to run pre-generated queries. While you can call the query method directly, be aware that retrieving all records from the database (without filters) may impact performance if the table grows large. Filtering and pagination should always be considered in production scenarios.
• DbContext Access: This example uses IDbContextFactory<T> to create DbContext instances. This is the recommended way when working outside of scoped services or when you need precise control over context lifetime.

The sample code below can serve as a reference when you need to build custom business workflows or wrap generated logic inside your own service layer. Remember that this is just a sample and not a real service.