Criando uma Aplicação .NET Completa com o Lino: Guia Passo a Passo

Instalando e configurando o Lino CLI

O primeiro passo para começar a trabalhar com o Lino CLI é instalar a ferramenta em seu ambiente de desenvolvimento. Ela é distribuída como uma dotnet global tool, o que significa que estará disponível para qualquer projeto .NET no seu computador. Antes de instalar, confirme que o SDK do .NET exigido pelos templates atuais está disponível, que o terminal consegue executar dotnet e que o diretório de ferramentas globais do .NET está no PATH.

Passo 1: Instalação

Para instalar (ou atualizar) o Lino CLI, execute o seguinte comando no terminal:

dotnet tool install --global Tolitech.Lino

Observações importantes:

• Se já houver uma versão instalada, você pode usar dotnet tool update --global Tolitech.Lino para atualizar.
• Verifique se o diretório de ferramentas globais do .NET está no PATH do sistema para que o comando lino funcione corretamente.

Passo 2: Configurar idioma

Após a instalação, é recomendado configurar o idioma (ou cultura) que o CLI irá utilizar em mensagens, prompts e logs:

lino preferences culture set

Você será solicitado a escolher entre os idiomas disponíveis. Essa configuração garante que todas as instruções e prompts apareçam de forma consistente no idioma desejado. Essa preferência altera mensagens, prompts e orientações localizadas da CLI; ela não renomeia entidades, serviços, módulos ou termos de negócio gerados no projeto.

Passo 3: Autenticação e registro

Para acessar todos os recursos do Lino, incluindo templates avançados, publicação de imagens Docker e integrações com serviços externos, é necessário estar autenticado.

- Caso ainda não possua cadastro, registre-se com o comando:

lino user register

- Caso já tenha cadastro, faça login com:

lino auth login

O que acontece: o CLI armazena um token de autenticação localmente, permitindo que você execute comandos que requerem acesso a recursos protegidos sem precisar se logar a cada uso. Mantenha esse token privado e evite compartilhar o mesmo perfil de usuário entre desenvolvedores, agentes de CI ou máquinas diferentes.

Passo 4: Verificação

Para confirmar que a instalação e autenticação foram realizadas com sucesso, execute:

lino --version

Se o comando retornar a versão instalada, você está pronto para começar a utilizar o Lino CLI em seus projetos.

Criando o projeto MyApp

Neste passo, vamos criar a estrutura inicial do projeto utilizando o Lino CLI. Este projeto servirá como base para demonstrar a criação de serviços, módulos, front-end e toda a integração de eventos. Um projeto Lino não é apenas uma pasta com uma solution: ele define convenções para fronteiras de serviço, bibliotecas compartilhadas, host Aspire, estrutura de frontend, testes, gerenciamento de pacotes, analyzers e configurações que os próximos comandos reutilizam.

Passo 1: Executando o comando de criação

Para criar um novo projeto, execute o comando abaixo no terminal:

lino project new

O CLI irá guiá-lo passo a passo, solicitando informações como:

• Nome do projeto: usaremos MyApp, mas você pode escolher qualquer nome que desejar;
• Recursos adicionais: analisadores de código, cache distribuído, suporte a eventos assíncronos, etc.

Passo 2: Configurando recursos essenciais

Para este projeto, recomendamos habilitar os seguintes recursos desde o início:

• Analisadores de código: para garantir que o código esteja seguindo boas práticas e padrões consistentes, prevenindo erros comuns de implementação;
• Cache distribuído: melhora a performance da aplicação em cenários com múltiplos serviços, evitando consultas desnecessárias ao banco de dados;
• Comunicação assíncrona: habilita o uso de eventos e filas para integração entre serviços, garantindo escalabilidade e desacoplamento.

É importante habilitar todas essas opções neste projeto, pois criaremos múltiplos serviços que irão se comunicar através de eventos de integração. Isso permitirá que você compreenda como estruturar sistemas modulares e distribuídos usando o Lino.

Passo 3: Estrutura gerada

Após a execução do comando e configuração dos recursos, o CLI irá gerar a estrutura inicial do projeto. Ela incluirá:

• Pastas de serviços e módulos;
• Templates para front-end (se aplicável);
• Configurações iniciais de cache, eventos e integrações;
• Arquivos de solução (.slnx) e projeto (.csproj) prontos para compilação.

Agora seu projeto MyApp está pronto para receber os serviços, módulos, entidades e front-end que configuraremos nos próximos passos. Antes de continuar, abra a solução gerada e execute dotnet build para confirmar que referências, source generators, templates, arquivos de projeto e configuração inicial estão coerentes.

Adicionando a aplicação web Backoffice

Um sistema completo normalmente precisa de pelo menos uma aplicação web para operar o domínio. Neste guia, a aplicação se chama Backoffice e representa uma interface interna para administradores, gestores ou usuários operacionais acompanharem produtos, categorias, estoques, vendas e demais informações do sistema.

A aplicação web não substitui os serviços de domínio. Ela atua como ponto de entrada visual para consumir APIs, acionar Commands, consultar Queries e expor telas coerentes com as regras já modeladas nos serviços.

Passo 1: Executando o comando de criação

Para adicionar uma nova aplicação web ao projeto, utilize:

lino web-app new

O alias lino webapp new também está disponível para facilitar a digitação. Durante a execução, informe um nome claro para a aplicação web; neste exemplo, usaremos Backoffice.

lino web-app new --name Backoffice

Passo 2: Entendendo a estrutura gerada

Ao final do processo, o Lino cria a estrutura inicial da Web App em src/WebApps/<WebAppName>. Para uma aplicação Blazor, a estrutura pode incluir projetos server/client, recursos compartilhados, arquivos de localização, clients para consumo das APIs e convenções que serão usadas posteriormente por lino page new.

• Pastas para páginas, componentes, layouts, services e recursos da aplicação;
• Clientes HTTP e contratos necessários para consumir APIs expostas pelos serviços do projeto;
• Resources de localização e templates iniciais usados pela experiência web;
• Projetos client/server quando o tipo de aplicação exigir essa separação;
• Convenções de rotas, navegação e integração que serão reutilizadas na geração de páginas;
• Pontos de integração com autenticação e autorização quando a feature de auth for adicionada ao projeto.

Passo 3: Quando criar a Web App no fluxo

Se você já sabe que o sistema terá uma interface Blazor, crie a Web App logo no início, depois da criação do projeto. Assim, os serviços, módulos, entidades, APIs e páginas gerados depois já ficam alinhados com a aplicação web que irá consumi-los.

Esse fluxo é especialmente útil porque os serviços criados posteriormente também geram projetos tipados de Api.Contracts e Api.Client, consumidos pelo projeto Blazor. Com a Web App presente desde cedo, fica mais simples validar o caminho completo: domínio, API, contratos, HttpClient e tela.

Observações importantes

• O Backoffice deve consumir os dados por meio das APIs geradas, mantendo a lógica de negócio nos serviços e módulos corretos.
• Antes de expor páginas administrativas, revise autenticação, autorização, roles, permissões e políticas de acesso.
• Você pode criar múltiplas aplicações web, por exemplo um Backoffice interno e um Site público, quando públicos, permissões, deploys ou responsabilidades forem diferentes.
• Evite misturar fluxos públicos e administrativos na mesma Web App quando isso dificultar segurança, navegação, deploy ou ownership da equipe.

Com a aplicação web criada, o guia pode avançar para os serviços e módulos que fornecerão os dados e regras de negócio consumidos por essa interface.

Criando serviços e módulos

Nesta etapa, vamos construir os serviços e módulos que irão compor a aplicação. O objetivo é criar uma arquitetura modular e escalável, permitindo que diferentes áreas do sistema, como produtos, categorias, estoque, vendas e mídia, evoluam de forma independente, mantendo coesão e facilitando a manutenção. Serviços definem fronteiras de deploy e persistência; módulos organizam áreas de negócio dentro de um serviço modular. Antes de criar arquivos, avalie quais partes do domínio precisam de banco próprio, release independente, contrato de integração ou ownership separado.

Passo 1: Definindo os serviços

Inicialmente, criaremos os seguintes serviços, cada um com responsabilidades bem definidas:

• Catalog (modular) – responsável por gerenciar produtos, categorias e preços;
• Sales – responsável pelo processamento de vendas e pedidos;
• Stock – responsável pelo gerenciamento de estoques e movimentações;
• Security – responsável por autenticação, autorização e gerenciamento de usuários.

Para criar os serviços do exemplo, execute um comando para cada serviço. No wizard do Catalog, escolha arquitetura modular; nos demais, escolha a arquitetura adequada para uma fronteira simples.

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

Durante a execução do comando, o CLI irá solicitar:

• Nome do serviço: por exemplo, Catalog;
• Nome de exibição e estilo de arquitetura: escolha uma arquitetura simples para fronteiras compactas ou modular quando o serviço tiver áreas coesas independentes;
• Banco de dados: escolha a tecnologia que se adequa melhor ao seu projeto (SQL Server, PostgreSQL, etc.);

Passo 2: Criando módulos dentro de serviços

Nem todos os serviços precisam ser modulares. No nosso projeto, apenas o serviço Catalog terá módulos, para separar responsabilidades como merchandising e precificação.

Definimos para o serviço Catalog os seguintes módulos:

• Merchandising – gerenciamento de produtos e categorias;
• Pricing – gerenciamento de preços, promoções e histórico de alterações.

Para criar os módulos do Catalog, execute:

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

Você pode criar quantos módulos desejar dentro do serviço modular Catalog. Além disso, dependendo da complexidade, alguns módulos poderiam se tornar serviços independentes futuramente. A separação apresentada aqui é apenas didática e serve como exemplo de organização modular. Não use módulos apenas para criar pastas; use-os quando eles protegem uma área de negócio com entidades, casos de uso, APIs, migrations e eventos próprios.

Estrutura final do projeto

Após a criação dos serviços e módulos, sua solução deverá ter uma estrutura semelhante à seguinte:

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/

Explicação da estrutura:

• Services/: contém todos os serviços do sistema, cada um isolado com sua própria lógica de negócio, infraestrutura e hospedagem;
• Modules/: pastas dentro de serviços modulares, permitindo organizar funcionalidades específicas e manter código coeso;
• WebApps/: frontends associados ao sistema, já integrados aos serviços;
• Shared/: bibliotecas e recursos compartilhados entre serviços e frontends;
• tests/: testes unitários e de integração organizados por serviço e módulo.

Com essa estrutura modular, cada equipe ou desenvolvedor pode trabalhar de forma independente em diferentes partes do sistema, facilitando escalabilidade, manutenção e testes. Depois de criar serviços e módulos, execute dotnet build para confirmar que os projetos foram anexados corretamente à solução, ao host Aspire, aos projetos compartilhados e à estrutura de testes.

Adicionando autenticação e autorização

A autenticação e autorização são elementos essenciais de qualquer sistema moderno. Autenticação comprova quem é o usuário; autorização define o que esse usuário pode executar. No Lino CLI, a feature de auth gera a base necessária para usuários, papéis, permissões, tokens, políticas de acesso e integração com APIs.

Passo 1: Executando o comando de autenticação

Para adicionar os recursos de autenticação e autorização, utilize o comando:

lino feature auth add

O CLI irá guiá-lo pelas seguintes etapas:

• Escolha do serviço ou módulo: você precisa indicar onde os artefatos de autenticação serão instalados. No nosso projeto de exemplo, utilizamos o serviço Security, que centraliza toda a lógica de segurança do sistema;
• Configurações adicionais: criação de tabelas de usuários, papéis, permissões, tokens e configuração de políticas de acesso;
• Tempo de vida dos tokens: definição de expiração para access token e refresh token de acordo com a política de segurança do produto;
• Tipo do identificador do usuário: escolha do tipo usado pelo modelo de usuário e pelos contratos gerados.

Passo 2: Estrutura gerada

Após a execução do comando, o serviço Security conterá arquivos e pastas como:

• Domain/Entities: agregados, entidades e regras para usuários, papéis, permissões e tokens;
• Infrastructure/Persistence: configurações do banco de dados, mapeamentos do Entity Framework e migrations para tabelas de segurança;
• Application: Commands, Queries, Handlers, serviços de autenticação, geração de tokens, validação de credenciais e checagens de permissão;
• API/Host: endpoints para login, logout, cadastro, refresh token e operações protegidas;
• Integração com Web App: suporte para fluxos autenticados quando uma aplicação web estiver presente.

Com isso, sua aplicação terá autenticação robusta e controle de acesso granular, pronta para suportar múltiplos usuários e diferentes níveis de permissões. Ainda assim, código gerado deve ser tratado como uma base forte, não como a revisão final de segurança. Antes de produção, revise tempo de vida de tokens, desenho de permissões, política de senha, HTTPS, secrets, rate limiting, logs e configurações de deploy.

Adicionando Background Jobs

Em sistemas distribuídos e modulares, como o que estamos construindo com o Lino CLI, nem todos os serviços se comunicam diretamente entre si. Para garantir consistência e confiabilidade na troca de informações, utilizamos eventos de integração. Porém, para processar esses eventos de forma eficiente e assíncrona, precisamos de Background Jobs.

O Lino utiliza o padrão Outbox Pattern para garantir que todas as mensagens geradas pelos serviços sejam registradas de forma confiável antes de serem enviadas. Com isso, conseguimos:

• Evitar a perda de eventos em caso de falhas ou reinicializações do serviço;
• Garantir que a mesma mensagem seja enviada apenas uma vez;
• Permitir o reprocessamento de mensagens em caso de falha na entrega;
• Separar o processamento de eventos da lógica principal da aplicação, melhorando performance e escalabilidade.

Passo 1: Executando o comando

Para adicionar suporte a Background Jobs no seu projeto, execute o comando:

lino feature background-job add

O CLI irá solicitar que você selecione o serviço onde o Background Job será instalado. Geralmente, você escolherá o serviço que centraliza a produção de eventos, como Catalog ou Sales. Nas opções atuais, o wizard também pode solicitar o módulo, a biblioteca de jobs, se eventos de Outbox devem ser processados, o agendamento e o tamanho do lote. O fluxo dos templates atuais usa Hangfire para execução recorrente dos jobs.

Passo 2: Configurando a execução

Durante a configuração, você poderá definir:

• Intervalo de verificação: determina com que frequência o Background Job irá verificar a tabela Outbox para novas mensagens. Um intervalo muito curto pode aumentar o uso de recursos, enquanto um intervalo longo pode atrasar a entrega de eventos;
• Lote de registros processados por vez: controla quantos eventos serão lidos e enviados por execução. Lotes maiores podem aumentar a performance, mas exigem mais memória e processamento;
• Política de retries: em caso de falha no envio de mensagens, você poderá configurar quantas vezes o job tentará reenviar.

Esses parâmetros dependem do tamanho do seu sistema, da capacidade da máquina e do volume esperado de eventos.

Passo 3: Estrutura gerada

Após a configuração, o projeto terá um Background Job pronto para processar mensagens das tabelas Outbox em cada serviço.

1. O caso de uso altera o domínio e registra um evento de domínio ou integração.
2. A unidade de trabalho salva os dados de negócio e as mensagens de Outbox na mesma transação.
3. O Hangfire executa jobs recorrentes que leem mensagens pendentes em lotes.
4. As mensagens são publicadas no mecanismo de integração configurado, como RabbitMQ quando comunicação assíncrona estiver habilitada.
5. Mensagens concluídas, falhas, antigas ou presas podem ser tratadas pela lógica e configuração geradas para o job.

Com isso, você garante que todos os eventos de integração sejam processados de forma confiável e eficiente, permitindo que múltiplos serviços e módulos se comuniquem de forma assíncrona, sem impactar a performance do sistema principal. A regra operacional mais importante é manter a fronteira transacional clara: eventos que precisam ser enviados via Outbox devem ser criados no mesmo fluxo transacional da alteração de negócio que representam.

Criando entidades e enumerações

Nesta seção, vamos detalhar o design das entidades, enumerações e Value Objects da aplicação, mostrando em quais serviços e módulos cada item será criado.

1. Criando a entidade Category

Para criar a entidade Category no serviço Catalog e no módulo Merchandising, execute:

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

A entidade será criada no serviço Catalog e no módulo Merchandising com a seguinte estrutura:

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

2. Criando a entidade Product

Em seguida, criamos a entidade Product no mesmo serviço e módulo. Neste fluxo, o Value Object ProductDimension e a enum ProductStatus são configurados dentro do próprio wizard de criação da entidade, como parte do agregado Product:

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

Durante a execução, adicione as propriedades simples, o relacionamento com Category, a propriedade Dimensions do tipo Value Object e a propriedade Status do tipo 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 Configurando o Value Object ProductDimension dentro de Product

No cenário deste guia, ProductDimension não é criado por um comando separado. Ele é adicionado durante o lino entity new de Product, como a propriedade Dimensions, e representa as dimensões do produto:

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

Observação: o comando lino value-object new existe para cenários em que o Value Object precisa ser criado separadamente. Nesses casos, use os argumentos do serviço e do módulo de destino:

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

2.2 Configurando a Enum ProductStatus dentro de Product

Da mesma forma, ProductStatus é configurada dentro do lino entity new de Product, como a propriedade Status. Ela define o status do produto:

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

Observação: o comando lino enumeration new também pode ser usado quando uma enum precisa ser criada separadamente em outro cenário:

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

3. Adicionando novas propriedades

Com a evolução do projeto, podemos editar entidades existentes para adicionar novas propriedades. Por exemplo, adicionaremos uma lista de imagens à entidade Product:

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

Dentro desse mesmo fluxo, criamos a propriedade Images do tipo List<ProductImage>. Como ProductImage pertence ao agregado Product, sua estrutura também é configurada durante o lino entity edit de Product:

┌────┬────┬───────────────┬────────────────────┬────────┬──────────┬────────────────┐
│ 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<ProductImage> │        │          │                │
└────┴────┴───────────────┴────────────────────┴────────┴──────────┴────────────────┘

3.1 Configurando ProductImage dentro de Product

ProductImage não é criado por um comando separado neste cenário. Ele é configurado como item da coleção Images durante a edição de Product e possui a seguinte estrutura:

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

Observação: o comando lino entity new existe para criar entidades independentes em outros cenários. Quando a entidade não faz parte da edição de um agregado existente, use:

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

4. Criando entidades para outros serviços

No serviço Sales, criamos a entidade ProductSnapshot, que será alimentada pelos eventos de integração. Como o Id original da entidade Product vem do serviço Catalog, ele não pode ser auto-incremental aqui.

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     │                │
└────┴────┴───────────────┴─────────┴────────┴──────────┴────────────────┘

Observação: apenas os campos essenciais foram replicados no ProductSnapshot para o serviço Sales. Entidades complementares, como Customer, Order e StockItem, não serão detalhadas aqui para simplificar a documentação. O ProductSnapshot funciona como uma shadow entity: uma cópia local, mínima e controlada de dados cujo dono está em outro serviço. Isso permite que Sales consulte os dados necessários de produto sem depender diretamente da entidade ou do banco do Catalog.

Esse tipo de estrutura também poderia ser criado pelo comando lino shadow new, alias de lino shadow-entity new. Nesse fluxo, o Lino copia a estrutura de uma entidade de outro serviço ou módulo e permite selecionar apenas as propriedades que fazem sentido para o contexto consumidor.

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

No exemplo, a entidade de origem é Catalog.Merchandising.Product e o destino é o serviço Sales, mantendo somente os campos necessários para vendas.

Criando eventos e seus manipuladores

Recapitulando, no tópico anterior criamos no serviço modular Catalog.Merchandising as entidades Product, Category e ProductImage, enquanto no serviço Sales criamos a entidade ProductSnapshot.

Agora, vamos criar eventos de domínio e eventos de integração. O objetivo é que, ao criar ou atualizar produtos no serviço Catalog, essas alterações sejam replicadas para os serviços consumidores, como Sales e Stock.

1. Criando eventos de domínio

O primeiro passo é criar os eventos de domínio ProductCreated e ProductUpdated com o comando:

lino event new

Durante a criação, podemos associar o evento a um manipulador e, simultaneamente, configurar o disparo de um evento de integração. Isso centraliza a criação de todo o fluxo necessário.

┌──────────────────────────────────────────────────────┬────────────────────────────────┐
│ 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                 │
└──────────────────────────────────────────────────────┴────────────────────────────────┘

Da mesma forma, criamos o evento 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                   │
└──────────────────────────────────────────────────────┴────────────────────────────────┘

Com isso, temos:

• Eventos de domínio criados (ProductCreated e ProductUpdated);
• Manipuladores de eventos de domínio correspondentes;
• Eventos de integração registrados na Outbox automaticamente pelo manipulador de eventos de domínio.

2. Criando manipuladores de eventos de integração

O próximo passo é definir quais serviços irão consumir os eventos de integração. Para isso, usamos:

lino event-handler new

O fluxo de criação envolve:

• Selecionar o serviço, módulo e entidade que conterá o manipulador;
• Selecionar o evento de integração que será consumido e de qual serviço/módulo/entidade ele virá.

Por exemplo, no serviço Sales criamos os manipuladores para ProductCreated e ProductUpdated que irão consumir os eventos disparados pelo 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    │
└────────────────────────────────────────────┴───────────────────┘

Com isso, temos dois manipuladores de eventos de integração no serviço Sales, consumindo apenas os campos necessários dos eventos de integração do Catalog.Merchandising. Isso garante que as tabelas replicadas mantenham apenas os dados essenciais, otimizando armazenamento e desempenho. Em termos de arquitetura, o fluxo esperado é: o Command Handler altera o agregado, o evento de domínio é levantado, o manipulador prepara o evento de integração, a Outbox armazena a mensagem, o Background Job processa a pendência e o mecanismo de mensageria entrega a mensagem aos consumidores. Isso evita acoplamento síncrono entre serviços e reduz o risco de o banco ser alterado sem que o evento correspondente seja publicado.

Gerando páginas web, APIs, Commands e Queries

Uma das grandes vantagens do Lino CLI é permitir a criação integrada de páginas web, APIs, Commands e Queries de forma automatizada, simplificando todo o fluxo de desenvolvimento. Quando o modelo de domínio já está estável o suficiente, esse comando cria um caminho completo da tela até a persistência, tornando visível para o usuário final o trabalho de modelagem feito nas etapas anteriores. Para iniciar, basta executar o comando:

lino page new

Durante o processo, você irá:

• Selecionar o serviço, módulo e entidade que deseja expor;
• Escolher o tipo e o nome da página que será gerada;
• Escolher os campos que farão parte da listagem;
• Gerar automaticamente páginas de listagem (grid paginado) e formulário de criação/edição;
• Gerar classes de HttpClient para consumo pelo frontend;
• Criar contratos de request/response e todas as APIs REST necessárias (POST, PUT, PATCH, DELETE e GET);
• Criar Commands, Queries, Handlers e validators, que vão até o banco de dados garantindo o fluxo completo de CRUD.

Com esse comando, você obtém uma aplicação funcional sem precisar escrever manualmente a camada de interface, APIs e lógica de negócio, mantendo o padrão e a consistência entre serviços. Mesmo assim, revise regras de negócio e validações depois da geração, porque nem toda regra pode ser inferida apenas pelos metadados das propriedades.

Para este projeto, podemos gerar as páginas integradas para as seguintes entidades:

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

Após gerar as páginas, APIs e Commands/Queries, a aplicação estará pronta para interagir de forma completa entre frontend e backend, com validações, rotas e persistência já configuradas automaticamente pelo Lino CLI. Execute dotnet build após a geração para identificar cedo referências quebradas, contratos inconsistentes ou impactos de mudanças recentes no modelo.

Criando e aplicando migrations

Depois de criar ou alterar entidades, Value Objects, enumerações, relacionamentos, autenticação, suporte a tenant ou persistência de Background Jobs, gere migrations para manter banco de dados e código alinhados. A migration transforma a mudança de modelo em um artefato explícito, versionável e revisável.

O Lino CLI coordena esse processo com Entity Framework, selecionando o serviço/módulo correto, usando a versão atual do serviço e organizando os scripts gerados para facilitar rastreabilidade.

Passo 1: Criando uma migration

Para criar uma nova migration, execute:

lino database migrations add

O comando também pode aceitar aliases como lino database migrations new e lino database migrations create, mas a forma preferida na documentação é add.

Durante a execução, você deverá informar:

• O serviço que receberá a migration, por exemplo Catalog;
• O módulo afetado, quando o serviço for modular, por exemplo Merchandising;
• A versão atual do serviço, lida a partir de src/Services/<ServiceName>/version.txt;
• Uma descrição objetiva para a migration, como Initial migration ou 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 │
└───────────────────────────────────────────┴───────────────────┘

Quando você já sabe o serviço e o módulo, pode informar esses dados diretamente:

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

Passo 2: O que é gerado

Ao confirmar a criação, o Lino prepara os comandos corretos do Entity Framework para o projeto de persistência do serviço ou módulo selecionado. Em um serviço modular, a migration permanece isolada no módulo correspondente, evitando misturar alterações de contextos diferentes.

• Uma nova migration de banco de dados associada à versão atual do serviço;
• O script SQL correspondente, organizado na camada de persistência, em um caminho versionado como /scripts/<version>/<nome do arquivo>;
• Artefatos compatíveis com a estrutura de Infrastructure/Persistence do serviço ou módulo selecionado;
• Histórico rastreável para relacionar versão de serviço, mudanças de schema e release da aplicação.

Passo 3: Listando e aplicando migrations

Antes de aplicar alterações em um banco, liste as migrations conhecidas e confirme se a migration esperada está presente:

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

Para aplicar migrations no ambiente configurado:

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

Em desenvolvimento local, esse fluxo acelera a validação do modelo. Em ambientes compartilhados ou produção, aplique migrations pelo processo de deploy definido pela equipe, com revisão do script, aprovação e backup quando necessário.

Passo 4: Revertendo ou removendo em ambiente controlado

Use revert quando precisar voltar uma migration aplicada em um ambiente controlado, entendendo que a operação pode executar comandos destrutivos dependendo do conteúdo da migration:

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

Use remove para descartar a última migration ainda não consolidada, normalmente antes de commitar ou publicar a alteração:

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

Boas práticas

• Crie migrations sempre que houver alterações no modelo persistido: novas entidades, propriedades, relações, índices, constraints, tabelas de auth ou tabelas de Outbox.
• Revise o código e o SQL gerados antes de aplicar em ambientes compartilhados.
• Tenha atenção especial com renames, mudanças de tipo, drops de coluna, alterações de chave, mudanças de schema e operações que podem causar perda de dados.
• Mantenha a versão do serviço alinhada aos scripts gerados para facilitar auditoria, rollback planejado e comunicação de release.
• Depois de criar a migration, execute build e testes relevantes para confirmar que domain, persistence, APIs e páginas geradas continuam coerentes.

Seguindo esse fluxo, o banco de dados permanece consistente com o modelo de domínio definido no Lino, e cada mudança de schema fica documentada, rastreável e pronta para ser revisada antes do deploy.

Passo 5: Validando a aplicação localmente

Com projeto, Web App, serviços, módulos, entidades, migrations, APIs, Commands e Queries prontos, valide a aplicação antes de gerar imagens Docker. Primeiro, compile a solução para confirmar que todos os projetos, contratos e clients gerados continuam coerentes:

dotnet build

Em seguida, execute a aplicação pelo AppHost do Aspire:

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

Use o dashboard do Aspire para conferir se APIs, Web App, banco de dados, cache, mensageria e Background Jobs subiram corretamente. Depois, teste os fluxos principais no Backoffice: páginas geradas, chamadas do Blazor para os projetos Api.Client, migrations aplicadas, autenticação quando habilitada, e eventos ou jobs quando fizerem parte do cenário.

Quando a aplicação compilar, executar localmente e os fluxos principais estiverem validados, o projeto estará pronto para a etapa de empacotamento.

Gerando imagens Docker

Depois que a aplicação compila, roda localmente pelo AppHost e os fluxos principais foram testados, você pode gerar imagens Docker dos serviços e aplicações web para posterior publicação em um registro de contêineres. Use lino build quando os itens selecionados estiverem prontos para empacotamento como imagens.

O Lino CLI simplifica esse processo com o comando:

lino build

Ao executar, você verá uma lista de todos os serviços e aplicações web disponíveis no projeto, juntamente com suas versões atuais:

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|

Você pode selecionar um ou mais serviços e aplicações web para gerar imagens simultaneamente. Basta marcar os itens desejados.

Em seguida, será solicitado escolher como deseja atualizar a versão das imagens geradas. As opções disponíveis são:

• Manter a versão atual – não altera a versão existente;
• Patch – incrementa a versão de patch (ex.: 0.1.0 → 0.1.1);
• Minor – incrementa a versão menor (ex.: 0.1.0 → 0.2.0);
• Major – incrementa a versão principal (ex.: 0.1.0 → 1.0.0).

Após selecionar os serviços e definir o incremento de versão, o Lino CLI realiza:

• Build do código de cada serviço e aplicação web;
• Geração da imagem Docker correspondente;
• Aplicação da tag com a versão definida;
• Disponibilização das imagens para publicação em seu registro de contêineres;
• Uso de parâmetros de publish como -c Release, -p:PublishProfile=DefaultContainer, -p:ContainerRepository, -p:ContainerImageTag e -p:ContainerLabelVersion, conforme o tipo de projeto gerado.

Ao final do processo, considerando que todos os serviços e aplicações web foram selecionados, as imagens geradas terão a seguinte estrutura:

• 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

Em termos gerais, serviços simples tendem a gerar repositórios como project-name/services/service-name-api:1.2.3, serviços modulares usam hosts como project-name/services/service-name-host:1.2.3, e aplicações Blazor usam caminhos como project-name/webapps/webapp-name:1.2.3.

Observação: Esse processo garante consistência entre o código e a versão das imagens Docker, facilitando o deploy e a manutenção de múltiplos ambientes, além de permitir que cada serviço seja isolado em contêineres independentes. Depois que a imagem local for gerada, publique-a no registro usado pela sua plataforma de deploy, como Docker Hub, GitHub Container Registry, AWS ECR, Azure Container Registry ou outro registro compatível com OCI. Não inclua secrets, connection strings de produção ou credenciais dentro da imagem.

Criando versões na aplicação

O Lino mantém a versão operacional de cada serviço em src/Services/<ServiceName>/version.txt e de cada aplicação web em src/WebApps/<WebAppName>/version.txt. Isso permite planejar releases independentes para cada item implantável.

Antes de alterar versões, inspecione o estado atual:

lino version list

Use lino version show quando precisar consultar um serviço ou aplicação web específica.

Incrementar novas versões aos serviços ou aplicações web é um processo simples e centralizado no Lino CLI. Basta executar o comando:

lino version bump

Assim como na geração de imagens Docker, ao executar esse comando você verá uma lista completa de todos os serviços e aplicações web do seu projeto. Apenas os itens que você selecionar terão sua versão incrementada, enquanto os demais permanecerão inalterados.

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|

Após selecionar os itens desejados, você será solicitado a escolher o tipo de incremento de versão. As opções disponíveis são:

• Patch – pequenas correções sem impacto funcional;
• Minor – adição de novas funcionalidades compatíveis com versões anteriores;
• Major – alterações que podem quebrar compatibilidade com versões anteriores.

É importante destacar que as versões dos serviços e aplicações web têm impacto direto em:

• As tags das imagens Docker;
• As pastas utilizadas para armazenar scripts gerados pelas migrações de banco de dados;
• O controle de releases e histórico do projeto;
• Notas de release, manifests de deploy e comunicação com consumidores de API.

Antes de aplicar um bump, revise mudanças de código, migrations, eventos de integração, contratos de API e alterações no frontend que fazem parte do release. Uma versão Patch deve representar correções compatíveis, Minor deve representar adições compatíveis, e Major deve ser reservado para mudanças que exigem adaptação de consumidores.

Com isso, concluímos o guia passo a passo de todos os comandos essenciais para a construção de um projeto web utilizando o Lino CLI, desde a instalação, criação de serviços, entidades, eventos e páginas, até a geração de imagens Docker e versionamento. O fluxo completo fica rastreável: modelar domínio, gerar casos de uso e telas, validar com builds e testes, criar migrations, publicar imagens com tags de versão e liberar cada serviço ou aplicação web com um valor SemVer explícito.

Não deixe de acompanhar nosso canal no YouTube para acompanhar tutoriais detalhados, demonstrações práticas e dicas de uso da ferramenta, desde operações simples até recursos avançados.