Building a Complete .NET Application with Lino: Step-by-Step Guide

Installing and configuring Lino CLI

The first step to start working with the Lino CLI is to install the tool in your development environment. It is distributed as a dotnet global tool, which means it will be available for any .NET project on your computer. Before installing, confirm that the .NET SDK required by the current templates is available, that the terminal can run dotnet and that the .NET global tools directory is in the PATH.

Step 1: Installation

To install (or update) Lino CLI, run the following command in the terminal:

dotnet tool install --global Tolitech.Lino

Important notes:

• If there is already a version installed, you can use dotnet tool update --global Tolitech.Lino to update.
• Verify that the .NET global tools directory is in the system PATH so the lino command works correctly.

Step 2: Configure language

After installation, we recommend configuring the language (or culture) that the CLI will use in messages, prompts and logs:

lino preferences culture set

You will be asked to choose from available languages. This setting ensures that all instructions and prompts appear consistently in the desired language. This preference changes CLI localized messages, prompts, and guidance; it does not rename entities, services, modules or business terms generated in the project.

Step 3: Authentication and registration

To access all Lino features, including advanced templates, Docker image publishing, and integrations with external services, you must be authenticated.

- If you haven't registered yet, register with the command:

lino user register

- If you have already registered, log in with:

lino auth login

What happens: the CLI stores an authentication token locally, allowing you to run commands that require access to protected resources without having to log in every time. Keep this token private and avoid sharing the same user profile between different developers, CI agents, or machines.

Step 4: Verification

To confirm that installation and authentication were successful, run:

lino --version

If the command returns the installed version, you are ready to start using the Lino CLI in your projects.

Creating the MyApp project

In this step, we will create the initial structure of the project using the Lino CLI. This project will serve as the basis for demonstrating the creation of services, modules, frontend and the full event integration flow. A Lino project is not just a folder with a solution: it defines conventions for service boundaries, shared libraries, Aspire host, frontend framework, tests, package management, analyzers, and configurations that the next commands reuse.

Step 1: Running the create command

To create a new project, run the command below in the terminal:

lino project new

CLI will guide you step by step, asking for information such as:

• Project name: we will use MyApp, but you can choose any name you like;
• Additional features: code analyzers, distributed caching, asynchronous event support, etc.

Step 2: Configuring essential features

For this project, we recommend enabling the following features from the beginning:

• Code analyzers: to ensure that the code is following good practices and consistent standards, preventing common implementation errors;
• Distributed cache: improves application performance in scenarios with multiple services, avoiding unnecessary database queries;
• Asynchronous communication: enables the use of events and queues for integration between services, ensuring scalability and decoupling.

It is important to enable all these options in this project, as we will create multiple services that will communicate through integration events. This will allow you to understand how to structure modular and distributed systems using Lino.

Step 3: Generated structure

After executing the command and configuring the resources, the CLI will generate the initial project structure. It will include:

• Services and modules folders;
• Frontend templates (if applicable);
• Initial cache settings, events and integrations;
• Solution (.slnx) and project (.csproj) files ready for compilation.

Now your MyApp project is ready to receive the services, modules, entities and frontend that we will configure in the next steps. Before continuing, open the generated solution and run dotnet build to confirm that references, source generators, templates, project files and initial configuration are coherent.

Adding the Backoffice web application

A complete system typically needs at least one web application to operate the domain. In this guide, the application is called Backoffice and represents an internal interface for administrators, managers or operational users to monitor products, categories, inventory, sales and other system information.

The web application does not replace domain services. It acts as a visual entry point to consume APIs, trigger Commands, run Queries and display screens consistent with the rules already modeled in the services.

Step 1: Running the create command

To add a new web application to the project, use:

lino web-app new

The alias lino webapp new is also available to make typing easier. During execution, provide a clear name for the web application; in this example, we will use Backoffice.

lino web-app new --name Backoffice

Step 2: Understanding the generated structure

At the end of the process, Lino creates the initial Web App structure in src/WebApps/<WebAppName>. For a Blazor application, the structure may include server/client projects, shared resources, localization files, clients for consuming APIs, and conventions that will be used later by lino page new.

• Folders for pages, components, layouts, services and application resources;
• HTTP clients and contracts required to consume APIs exposed by project services;
• Localization resources and initial templates used by the web experience;
• Client/server projects when the type of application requires this separation;
• Route, navigation and integration conventions that will be reused in page generation;
• Integration points with authentication and authorization when the auth feature is added to the project.

Step 3: When to create the Web App in the flow

If you already know the system will have a Blazor interface, create the Web App early, right after creating the project. This way, the services, modules, entities, APIs and pages generated later are already aligned with the web application that will consume them.

This flow is especially useful because services created later also generate typed Api.Contracts and Api.Client projects, consumed by the Blazor project. With the Web App present from the beginning, it becomes simpler to validate the complete path: domain, API, contracts, HttpClient and screen.

Important Notes

• The Backoffice must consume the data through the generated APIs, maintaining the business logic in the correct services and modules.
• Before exposing administrative pages, review authentication, authorization, roles, permissions, and access policies.
• You can create multiple web applications, for example an internal Backoffice and a public Site, when audiences, permissions, deployments or responsibilities are different.
• Avoid mixing public and administrative flows in the same Web App when this makes security, navigation, deployment or team ownership difficult.

With the web application created, the guide can move on to the services and modules that will provide the data and business rules consumed by this interface.

Creating services and modules

In this step, we will build the services and modules that will make up the application. The goal is to create a modular and scalable architecture, allowing different areas of the system, such as products, categories, inventory, sales and media, to evolve independently while maintaining cohesion and making maintenance easier. Services define deployment and persistence boundaries; modules organize business areas within a modular service. Before creating files, evaluate which parts of the domain need their own database, independent release, integration contract or separate ownership.

Step 1: Defining the services

Initially, we will create the following services, each with well-defined responsibilities:

• Catalog (modular) – responsible for managing products, categories and prices;
• Sales – responsible for processing sales and orders;
• Stock – responsible for managing stocks and movements;
• Security – responsible for authentication, authorization and user management.

To create the example services, run one command for each service. In the Catalog wizard, choose modular architecture; for the others, choose the architecture appropriate for a simple boundary.

lino service new --name Catalog
lino service new --name Sales
lino service new --name Stock
lino service new --name Security

During command execution, the CLI will ask:

• Service name: for example, Catalog;
• Display name and architectural style: choose a simple architecture for compact boundaries or modular when the service has independent cohesive areas;
• Database: choose the technology that best suits your project (SQL Server, PostgreSQL, etc.);

Step 2: Creating modules inside services

Not all services need to be modular. In our project, only the Catalog service will have modules, to separate responsibilities such as merchandising and pricing.

We define the following modules for the Catalog service:

• Merchandising – product and category management;
• Pricing – price, promotion and change history management.

To create the Catalog modules, run:

lino module new --service Catalog --name Merchandising
lino module new --service Catalog --name Pricing

You can create as many modules as you want within the modular Catalog service. Depending on complexity, some modules could also become independent services in the future. The separation presented here is for didactic purposes only and serves as an example of modular organization. Don't just use modules to create folders; use them when they protect a business area with its own entities, use cases, APIs, migrations and events.

Final project structure

After creating the services and modules, your solution should have a structure similar to the following:

MyApp/
└── src/
    ├── Aspire/
    ├── Integrations/
    ├── Services/
    │   ├── Catalog/
    │   │   ├── Modules/
    │   │   │   ├── Merchandising/
    │   │   │   └── Pricing/
    │   │   ├── MyApp.Catalog.Host
    │   │   └── MyApp.Catalog.Infrastructure
    │   ├── Sales/
    │   ├── Security/
    │   ├── Shared/
    │   └── Stock/
    └── WebApps/
        ├── Backoffice/
        │   ├── Services/
        │   │   ├── Catalog/
        │   │   ├── Sales/
        │   │   ├── Security/
        │   │   └── Stock/
        │   ├── MyApp.WebApp.Backoffice
        │   └── MyApp.WebApp.Backoffice.Client
        └── Shared/
            └── MyApp.WebApp.Shared
└── tests/
    └── Services/
        ├── Catalog/
        │   ├── Merchandising/
        │   └── Pricing/
        ├── Sales/
        ├── Security/
        ├── Shared/
        └── Stock/

Structure Explanation:

• Services/: contains all system services, each isolated with its own business logic, infrastructure and hosting;
• Modules/: folders within modular services, allowing you to organize specific functionalities and maintain cohesive code;
• WebApps/: frontends associated with the system, already integrated with services;
• Shared/: libraries and resources shared between services and frontends;
• tests/: unit and integration tests organized by service and module.

With this modular structure, each team or developer can work independently on different parts of the system, making scalability, maintenance and testing easier. After creating services and modules, run dotnet build to confirm that projects are correctly attached to the solution, host Aspire, shared projects, and testing framework.

Adding authentication and authorization

Authentication and authorization are essential elements of any modern system. Authentication proves who the user is; authorization defines what that user can do. In Lino CLI, the auth feature generates the required foundation for users, roles, permissions, tokens, access policies and API integration.

Step 1: Running the authentication command

To add authentication and authorization features, use the command:

lino feature auth add

The CLI will guide you through the following steps:

• Choice of service or module: you need to indicate where the authentication artifacts will be installed. In our example project, we use the Security service, which centralizes all of the system's security logic;
• Additional settings: creation of user, role, permission and token tables, and configuration of access policies;
• Token lifetime: definition of expiration for access token and refresh token in accordance with the product's security policy;
• User identifier type: choosing the type used by the user model and generated contracts.

Step 2: Generated structure

After executing the command, the Security service will contain files and folders such as:

• Domain/Entities: aggregates, entities and rules for users, roles, permissions and tokens;
• Infrastructure/Persistence: database configurations, Entity Framework mappings and migrations for security tables;
• Application: Commands, Queries, Handlers, authentication services, token generation, credential validation and permission checks;
• API/Host: endpoints for login, logout, registration, refresh token and protected operations;
• Integration with Web App: support for authenticated flows when a web application is present.

With this, your application will have robust authentication and granular access control, ready to support multiple users and different permission levels. Still, generated code should be treated as a strong foundation, not as the final security review. Before production, review token lifetime, permissions design, password policy, HTTPS, secrets, rate limiting, logs and deployment configurations.

Adding Background Jobs

In distributed and modular systems, like the one we are building with Lino CLI, not all services communicate directly with each other. To ensure consistency and reliability in the exchange of information, we use integration events. However, to process these events efficiently and asynchronously, we need Background Jobs.

Lino uses the Outbox Pattern to ensure that all messages generated by the services are reliably recorded before they are sent. This allows us to:

• Avoid losing events in case of service failures or restarts;
• Ensure that the same message is sent only once;
• Allow reprocessing of messages in case of delivery failure;
• Separate event processing from the main application logic, improving performance and scalability.

Step 1: Executing the command

To add Background Jobs support to your project, run the command:

lino feature background-job add

The CLI will ask you to select the service where the Background Job will be installed. Usually, you will choose the service that centralizes event production, such as Catalog or Sales. In the current options, the wizard can also ask for the module, the job library, whether Outbox events should be processed, the schedule and the batch size. The current template flow uses Hangfire for recurring job execution.

Step 2: Configuring the execution

During configuration, you will be able to define:

• Check interval: determines how often the Background Job will check the table Outbox for new messages. Too short an interval can increase resource usage, while too long an interval can delay event delivery;
• Batch of records processed at a time: controls how many events will be read and sent per run. Larger batches can increase performance, but require more memory and processing;
• Retry policy: if message sending fails, you can configure how many times the job will try to resend.

These parameters depend on the size of your system, the machine capacity and the expected event volume.

Step 3: Generated structure

After configuration, the project will have a Background Job ready to process messages from the Outbox tables in each service.

1. The use case changes the domain and records a domain or integration event.
2. The unit of work saves the business data and messages from Outbox in the same transaction.
3. Hangfire runs recurring jobs that read pending messages in batches.
4. Messages are published to the configured integration engine such as RabbitMQ when asynchronous communication is enabled.
5. Completed, failed, old, or stuck messages can be handled by the logic and configuration generated for the job.

This ensures that all integration events are processed reliably and efficiently, allowing multiple services and modules to communicate asynchronously without impacting the performance of the main system. The most important operational rule is to keep the transactional boundary clear: events that need to be sent via Outbox must be created in the same transactional flow as the business change they represent.

Creating entities and enumerations

In this section, we will detail the design of the application's entities, enumerations and Value Objects, showing which services and modules each item will be created in.

1. Creating the entity Category

To create the Category entity in the Catalog service and the Merchandising module, run:

lino entity new --service Catalog --module Merchandising --name Category

The entity will be created in the Catalog service and in the Merchandising module with the following structure:

┌────┬────┬───────────────┬────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type   │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid   │        │    x     │       x        │
├────┼────┼───────────────┼────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string │   50   │    x     │                │
└────┴────┴───────────────┴────────┴────────┴──────────┴────────────────┘

2. Creating the entity Product

Next, we create the Product entity in the same service and module. In this flow, the ProductDimension Value Object and the ProductStatus enum are configured inside the entity creation wizard itself, as part of the Product aggregate:

lino entity new --service Catalog --module Merchandising --name Product

During execution, add the simple properties, the relationship with Category, the Dimensions property of type Value Object and the Status property of type Enum.

┌────┬────┬───────────────┬─────────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type        │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid        │        │    x     │       x        │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string      │  100   │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Description   │ string      │  500   │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Price         │ decimal     │        │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │ x  │ CategoryId    │ Category    │        │    x     │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Dimensions    │ ValueObject │        │          │                │
├────┼────┼───────────────┼─────────────┼────────┼──────────┼────────────────┤
│    │    │ Status        │ Enum        │        │    x     │                │
└────┴────┴───────────────┴─────────────┴────────┴──────────┴────────────────┘

2.1 Configuring the Value Object ProductDimension inside Product

In this guide scenario, ProductDimension is not created by a separate command. It is added during Product's lino entity new as the Dimensions property, and represents the product dimensions:

┌───────────────┬─────────┬────────┬──────────┐
│ Property name │ Type    │ Length │ Required │
├───────────────┼─────────┼────────┼──────────┤
│ Width         │ decimal │        │    x     │
├───────────────┼─────────┼────────┼──────────┤
│ Height        │ decimal │        │    x     │
├───────────────┼─────────┼────────┼──────────┤
│ Depth         │ decimal │        │    x     │
└───────────────┴─────────┴────────┴──────────┘

Note: the lino value-object new command exists for scenarios where the Value Object needs to be created separately. In these cases, use the target service and module arguments:

lino value-object new --service <ServiceName> --module <ModuleName> --name <ValueObjectName>

2.2 Configuring the Enum ProductStatus inside Product

Likewise, ProductStatus is configured inside Product's lino entity new as the Status property. It defines the product status:

┌───────┬──────────────┬──────────────┐
│ Value │ Name         │ Display Name │
├───────┼──────────────┼──────────────┤
│ 1     │ Active       │ Active       │
├───────┼──────────────┼──────────────┤
│ 2     │ Inactive     │ Inactive     │
├───────┼──────────────┼──────────────┤
│ 3     │ Discontinued │ Discontinued │
└───────┴──────────────┴──────────────┘

Note: the lino enumeration new command can also be used when an enum needs to be created separately in another scenario:

lino enumeration new --service <ServiceName> --module <ModuleName> --name <EnumerationName>

3. Adding new properties

As the project evolves, we can edit existing entities to add new properties. For example, we will add a list of images to the entity Product:

lino entity edit --service Catalog --module Merchandising --entity Product

Inside this same flow, we create the Images property of type List<ProductImage>. Because ProductImage belongs to the Product aggregate, its structure is also configured during Product's lino entity edit:

┌────┬────┬───────────────┬────────────────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type               │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid               │        │    x     │       x        │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string             │  100   │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Description   │ string             │  500   │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Price         │ decimal            │        │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │ x  │ CategoryId    │ EntityId           │        │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Dimensions    │ ValueObject        │        │          │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │    │ Status        │ Enum               │        │    x     │                │
├────┼────┼───────────────┼────────────────────┼────────┼──────────┼────────────────┤
│    │ x  │ Images        │ List │        │          │                │
└────┴────┴───────────────┴────────────────────┴────────┴──────────┴────────────────┘

3.1 Configuring ProductImage inside Product

ProductImage is not created by a separate command in this scenario. It is configured as an item in the Images collection during the edit of Product and has the following structure:

┌────┬────┬───────────────┬────────────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type           │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid           │        │    x     │       x        │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│    │ x  │ ProductId     │ EntityId       │        │    x     │                │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│    │    │ UploadDate    │ DateTimeOffset │        │    x     │                │
├────┼────┼───────────────┼────────────────┼────────┼──────────┼────────────────┤
│    │    │ Image         │ File           │        │    x     │                │
└────┴────┴───────────────┴────────────────┴────────┴──────────┴────────────────┘

Note: the lino entity new command exists to create independent entities in other scenarios. When the entity is not part of editing an existing aggregate, use:

lino entity new --service <ServiceName> --module <ModuleName> --name <EntityName>

4. Creating entities for other services

In the Sales service, we create the ProductSnapshot entity, which will be populated by integration events. Because the original Id of the Product entity comes from the Catalog service, it cannot be auto-incremental here.

lino entity new --service Sales --name ProductSnapshot

┌────┬────┬───────────────┬─────────┬────────┬──────────┬────────────────┐
│ PK │ FK │ Property name │ Type    │ Length │ Required │ Auto-increment │
├────┼────┼───────────────┼─────────┼────────┼──────────┼────────────────┤
│ x  │    │ Id            │ Guid    │        │    x     │                │
├────┼────┼───────────────┼─────────┼────────┼──────────┼────────────────┤
│    │    │ Name          │ string  │  100   │    x     │                │
├────┼────┼───────────────┼─────────┼────────┼──────────┼────────────────┤
│    │    │ Price         │ decimal │        │    x     │                │
└────┴────┴───────────────┴─────────┴────────┴──────────┴────────────────┘

Note: only the essential fields were replicated in ProductSnapshot for the Sales service. Complementary entities, such as Customer, Order and StockItem, will not be detailed here to keep the documentation simple. The ProductSnapshot works as a shadow entity: a local, minimal and controlled copy of data whose owner is in another service. This allows Sales to query the necessary product data without depending directly on the Catalog entity or database.

This type of structure could also be created by the lino shadow new command, an alias of lino shadow-entity new. In this flow, Lino copies the structure of an entity from another service or module and lets you select only the properties that make sense for the consuming context.

lino shadow new --service <ServiceName> --module <ModuleName> --name <ShadowEntityName>

In the example, the source entity is Catalog.Merchandising.Product and the target is the Sales service, keeping only the fields needed for sales.

Creating events and their handlers

To recap, in the previous topic we created the Product, Category and ProductImage entities in the modular service Catalog.Merchandising, while in the Sales service we created the ProductSnapshot entity.

Now, we will create domain events and integration events. The goal is for changes made when products are created or updated in the Catalog service to be replicated to consumer services, such as Sales and Stock.

1. Creating domain events

The first step is to create domain events ProductCreated and ProductUpdated with the command:

lino event new

During creation, we can associate the event with a handler and, at the same time, configure an integration event to be triggered. This centralizes the creation of the entire required flow.

┌──────────────────────────────────────────────────────┬────────────────────────────────┐
│ Question                                             │ Answer                         │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a service:                                    │ Catalog                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a module:                                     │ Merchandising                  │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a entity:                                     │ Product                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select the event type:                               │ Domain Event                   │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductCreated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Do you want to create an associated event handler?   │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Trigger a integration event?                         │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Choose the integration event to be triggered:        │ (Create new integration event) │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductCreated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Which model will be used for this integration event? │ Creation model                 │
└──────────────────────────────────────────────────────┴────────────────────────────────┘

In the same way, we create the event ProductUpdated:

┌──────────────────────────────────────────────────────┬────────────────────────────────┐
│ Question                                             │ Answer                         │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a service:                                    │ Catalog                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a module:                                     │ Merchandising                  │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select a entity:                                     │ Product                        │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Select the event type:                               │ Domain Event                   │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductUpdated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Do you want to create an associated event handler?   │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Trigger a integration event?                         │ Yes                            │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Choose the integration event to be triggered:        │ (Create new integration event) │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Enter the name of the event:                         │ ProductUpdated                 │
├──────────────────────────────────────────────────────┼────────────────────────────────┤
│ Which model will be used for this integration event? │ Update model                   │
└──────────────────────────────────────────────────────┴────────────────────────────────┘

With this, we have:

• Created domain events (ProductCreated and ProductUpdated);
• Corresponding domain event handlers;
• Integration events automatically recorded in the Outbox by the domain event handler.

2. Creating integration event handlers

The next step is to define which services will consume the integration events. To do this, we use:

lino event-handler new

The creation flow involves:

• Select the service, module and entity that will contain the handler;
• Select the integration event that will be consumed and which service/module/entity it will come from.

For example, in the Sales service, we create handlers for ProductCreated and ProductUpdated that will consume the events triggered by Catalog.Merchandising.Product:

┌────────────────────────────────────────────┬───────────────────┐
│ Question                                   │ Answer            │
├────────────────────────────────────────────┼───────────────────┤
│ Select a service:                          │ Sales             │
├────────────────────────────────────────────┼───────────────────┤
│ Select a entity:                           │ ProductSnapshot   │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event type:                     │ Integration Event │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's service to be consumed: │ Catalog           │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's module to be consumed:  │ Merchandising     │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's entity to be consumed:  │ Product           │
├────────────────────────────────────────────┼───────────────────┤
│ Choose the event to be consumed:           │ ProductCreated    │
├────────────────────────────────────────────┼───────────────────┤
│ Enter the name of the event handler:       │ ProductCreated    │
└────────────────────────────────────────────┴───────────────────┘

┌────────────────────────────────────────────┬───────────────────┐
│ Question                                   │ Answer            │
├────────────────────────────────────────────┼───────────────────┤
│ Select a service:                          │ Sales             │
├────────────────────────────────────────────┼───────────────────┤
│ Select a entity:                           │ ProductSnapshot   │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event type:                     │ Integration Event │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's service to be consumed: │ Catalog           │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's module to be consumed:  │ Merchandising     │
├────────────────────────────────────────────┼───────────────────┤
│ Select the event's entity to be consumed:  │ Product           │
├────────────────────────────────────────────┼───────────────────┤
│ Choose the event to be consumed:           │ ProductUpdated    │
├────────────────────────────────────────────┼───────────────────┤
│ Enter the name of the event handler:       │ ProductUpdated    │
└────────────────────────────────────────────┴───────────────────┘

With this, we have two integration event handlers in the Sales service, consuming only the necessary fields from the integration events from Catalog.Merchandising. This ensures that replicated tables retain only essential data, optimizing storage and performance. In architectural terms, the expected flow is: the Command Handler changes the aggregate, the domain event is raised, the handler prepares the integration event, the Outbox stores the message, the Background Job processes the pending item and the messaging mechanism delivers the message to consumers. This avoids synchronous coupling between services and reduces the risk of the database being changed without the corresponding event being published.

Generating web pages, APIs, Commands and Queries

One of the major advantages of Lino CLI is that it enables integrated creation of web pages, APIs, Commands and Queries in an automated way, simplifying the entire development flow. When the domain model is stable enough, this command creates a complete path from the screen to persistence, making the modeling work done in the previous steps visible to the end user. To start, simply run the command:

lino page new

During the process, you will:

• Select the service, module and entity you want to expose;
• Choose the type and name of the page that will be generated;
• Choose the fields that will be part of the list;
• Automatically generate listing pages (paginated grid) and creation/editing form;
• Generate HttpClient classes for consumption by the frontend;
• Create request/response contracts and all necessary REST APIs (POST, PUT, PATCH, DELETE and GET);
• Create Commands, Queries, Handlers and validators that reach the database, ensuring the complete CRUD flow.

With this command, you get a functional application without having to manually write the interface layer, APIs and business logic, while maintaining standards and consistency across services. Even so, review business rules and validations after generation, because not every rule can be inferred from property metadata alone.

For this project, we can generate integrated pages for the following entities:

• Catalog.Merchandising.Category
• Catalog.Merchandising.Product
• Sales.ProductSnapshot

After generating the pages, APIs and Commands/Queries, the application will be ready for complete frontend-backend interaction, with validations, routes and persistence already configured automatically by the Lino CLI. Run dotnet build after generation to identify broken references, inconsistent contracts, or impacts of recent model changes early.

Creating and applying migrations

After creating or changing entities, Value Objects, enumerations, relationships, authentication, tenant support or Background Jobs persistence, generate migrations to keep the database and code aligned. A migration turns the model change into an explicit, versionable and reviewable artifact.

The Lino CLI coordinates this process with Entity Framework, selecting the correct service/module, using the current service version and organizing the generated scripts to make traceability easier.

Step 1: Creating a migration

To create a new migration, run:

lino database migrations add

The command can also accept aliases like lino database migrations new and lino database migrations create, but the preferred form in the documentation is add.

During execution, you must inform:

• The service that will receive the migration, for example Catalog;
• The affected module, when the service is modular, e.g. Merchandising;
• The current version of the service, read from src/Services/<ServiceName>/version.txt;
• An objective description for the migration, such as Initial migration or Add product images.

┌───────────────────────────────────────────┬───────────────────┐
│ Question                                  │ Answer            │
├───────────────────────────────────────────┼───────────────────┤
│ Select a service:                         │ Catalog           │
├───────────────────────────────────────────┼───────────────────┤
│ Select a module:                          │ Merchandising     │
├───────────────────────────────────────────┼───────────────────┤
│ Current version of the service:           │ 0.1.0             │
├───────────────────────────────────────────┼───────────────────┤
│ Provide a description for this migration: │ Initial migration │
└───────────────────────────────────────────┴───────────────────┘

When you already know the service and the module, you can enter this data directly:

lino database migrations add --service <ServiceName> --module <ModuleName>

Step 2: What is generated

When you confirm creation, Lino prepares the correct Entity Framework commands for the selected service or module persistence project. In a modular service, the migration remains isolated in the corresponding module, avoiding mixed changes from different contexts.

• A new database migration associated with the current version of the service;
• The corresponding SQL script, organized in the persistence layer, in a versioned path like /scripts//;
• Artifacts compatible with the Infrastructure/Persistence structure of the selected service or module;
• Traceable history to relate service version, schema changes and application release.

Step 3: Listing and applying migrations

Before applying changes to a database, list the known migrations and confirm that the expected migration is present:

lino database migrations list --service <ServiceName> --module <ModuleName>

To apply migrations to the configured environment:

lino database migrations apply --service <ServiceName> --module <ModuleName>

In local development, this flow speeds up model validation. In shared or production environments, apply migrations through the deployment process defined by the team, with script review, approval and backup when needed.

Step 4: Reversing or removing in a controlled environment

Use revert when you need to roll back a migration applied in a controlled environment, understanding that the operation may execute destructive commands depending on the migration content:

lino database migrations revert --service <ServiceName> --module <ModuleName>

Use remove to discard the last uncommitted migration, usually before committing or publishing the change:

lino database migrations remove --service <ServiceName> --module <ModuleName>

Good practices

• Create migrations whenever there are changes to the persisted model: new entities, properties, relationships, indexes, constraints, auth tables or Outbox tables.
• Review the generated code and SQL before applying to shared environments.
• Pay special attention to renames, type changes, column drops, key changes, schema changes and operations that can cause data loss.
• Keep the service version aligned with generated scripts to facilitate auditing, planned rollback, and release communication.
• After creating the migration, run build and relevant tests to confirm that domain, persistence, APIs and generated pages remain coherent.

By following this flow, the database remains consistent with the domain model defined in Lino, and each schema change is documented, traceable and ready for review before deployment.

Step 5: Validating the application locally

With the project, Web App, services, modules, entities, migrations, APIs, Commands and Queries ready, validate the application before generating Docker images. First, build the solution to confirm that all generated projects, contracts and clients remain coherent:

dotnet build

Then run the application through the Aspire AppHost:

dotnet run --project src/Aspire/AppHost/<ProjectName>.AppHost.csproj

Use the Aspire dashboard to check whether APIs, Web App, database, cache, messaging and Background Jobs started correctly. Then test the main flows in the Backoffice: generated pages, Blazor calls to the Api.Client projects, applied migrations, authentication when enabled, and events or jobs when they are part of the scenario.

When the application builds, runs locally and the main flows are validated, the project is ready for the packaging step.

Generating Docker images

After the application builds, runs locally through the AppHost and the main flows have been tested, you can generate Docker images for the services and web applications for later publication to a container registry. Use lino build when the selected items are ready to be packaged as images.

The Lino CLI simplifies this process with the command:

lino build

When run, you will see a list of all services and web applications available in the project, along with their current versions:

Select the services or web applications you want to include in the build:

> [ ] Services
    [ ] Catalog |0.1.0|
    [ ] Sales |0.1.0|
    [ ] Security |0.1.0|
    [ ] Stock |0.1.0|
  [ ] Web applications
    [ ] Backoffice |0.1.0|

You can select one or more services and web applications to generate images simultaneously. Just select the desired items.

You will then be asked to choose how you want to update the version of the generated images. The available options are:

• Keep the current version – does not change the existing version;
• Patch – increments the patch version (e.g.: 0.1.0 → 0.1.1);
• Minor – increments the minor version (e.g.: 0.1.0 → 0.2.0);
• Major – increments the major version (e.g.: 0.1.0 → 1.0.0).

After selecting the services and defining the version increment, the Lino CLI performs:

• Build the code for each service and web application;
• Generation of the corresponding Docker image;
• Application of the tag with the defined version;
• Making images available for publication in your container registry;
• Using publish parameters like -c Release, -p:PublishProfile=DefaultContainer, -p:ContainerRepository, -p:ContainerImageTag and -p:ContainerLabelVersion, depending on the type of project generated.

At the end of the process, assuming all services and web applications were selected, the generated images will have the following structure:

• my-app/services/catalog-host - tag: 0.1.0
• my-app/services/sales-api - tag: 0.1.0
• my-app/services/security-api - tag: 0.1.0
• my-app/services/stock-api - tag: 0.1.0
• my-app/webapps/backoffice - tag: 0.1.0

Generally speaking, simple services tend to generate repositories like project-name/services/service-name-api:1.2.3, modular services use hosts as project-name/services/service-name-host:1.2.3, and Blazor applications use paths like project-name/webapps/webapp-name:1.2.3.

Note: This process ensures consistency between the code and the Docker image version, making deployment and maintenance across multiple environments easier, while also allowing each service to be isolated in independent containers. After the local image is generated, publish it to the registry used by your deployment platform, such as Docker Hub, GitHub Container Registry, AWS ECR, Azure Container Registry, or another OCI-compliant registry. Do not include secrets, production connection strings, or credentials within the image.

Creating versions in the application

Lino maintains the operational version of each service in src/Services/<ServiceName>/version.txt and each web application in src/WebApps/<WebAppName>/version.txt. This allows you to plan independent releases for each deployable item.

Before changing versions, inspect the current state:

lino version list

Use lino version show when you need to consult a specific service or web application.

Incrementing service or web application versions is a simple process centralized in Lino CLI. Just run the command:

lino version bump

Just like generating Docker images, when you run this command you will see a complete list of all services and web applications in your project. Only the items you select will have their version incremented, while the rest will remain unchanged.

Select the services or web applications that will have version changes:

> [ ] Services
    [ ] Catalog |0.1.0|
    [ ] Sales |0.1.0|
    [ ] Security |0.1.0|
    [ ] Stock |0.1.0|
  [ ] Web applications
    [ ] Backoffice |0.1.0|

After selecting the desired items, you will be asked to choose the type of version increment. The available options are:

• Patch – small corrections without functional impact;
• Minor – addition of new features compatible with previous versions;
• Major – changes that may break compatibility with previous versions.

It is important to highlight that service and web application versions have a direct impact on:

• Docker image tags;
• The folders used to store scripts generated by database migrations;
• Control of releases and project history;
• Release notes, deployment manifests and communication with API consumers.

Before applying a bump, review code changes, migrations, integration events, API contracts and frontend changes that are part of the release. A Patch version should represent compatible fixes, Minor should represent compatible additions, and Major should be reserved for changes that require consumers to adapt.

With this, we conclude the step-by-step guide to all the essential commands for building a web project using the Lino CLI, from installation, creation of services, entities, events and pages, to Docker image generation and versioning. The complete flow is traceable: modeling domain, generating use cases and screens, validating with builds and tests, creating migrations, publishing images with version tags and releasing each service or web application with an explicit SemVer value.

Don't forget to follow our channel on YouTube for detailed tutorials, practical demonstrations and tips for using the tool, from simple operations to advanced features.