Passo a Passo

Montagem básica inicial

Para utilizar o blazorpost boilerplate do Embrapa4dev é necessário executar os seguintes passos para criação de um novo projeto e aplicações no Embrapa I/O.

1. Configure um ambiente local de desenvolvimento em .NET, seguindo por exemplo o Tutorial para ambiente Windows e WSL.
2. Com o projeto já criado no Embrapa I/O, na etapa de criação de nova App, selecione o modelo (boilerplate): Embrapa4Dev: .NET Blazor + PostgreSQL, informe o nome Unix do repositório no Gitlab e clique no botão “Criar App”.
3. Aguarde a execução do autômato Genesis concluir a criação das soluções e repositório no Gitlab.
4. Solicite o client OIDC da sua solução no Keycloak institucional, por estágio (conforme descrito no item 5 do FAQ). Você receberá os valores de KEYCLOAK_AUTHORITY, KEYCLOAK_CLIENT_ID e KEYCLOAK_CLIENT_SECRET.
5. Caso a solução vá consumir dados corporativos (empregados, unidades, pessoas, localidades), solicite à equipe da SDSS a string de conexão do MongoDB do ETL corporativo (MONGO_CONNECTION_STRING / MONGO_DATABASE_NAME) e, se for exibir foto de empregado, as credenciais da API do Portal Embrapa (EMBRAPA_PORTAL_API_USERNAME / EMBRAPA_PORTAL_API_PASSWORD).
6. Realize as configurações do Cluster, Volumes e Variáveis de ambiente para a solução no estágio desejado (Ex. Alpha).
7. Crie a primeira Tag para publicação da versão.
8. Aguarde a conclusão da construção dos serviços e acesse a aplicação pela URL informada na solução do estágio.
9. Realize o login institucional pelo Keycloak.
10. O primeiro usuário a realizar este procedimento será registrado como o “Administrador” da solução.

Observações:

1. Caso o ambiente de destino esteja utilizando a solução Releaser do Embrapa I/O para deploy, atentar que todas as variáveis de configuração da solução devem estar cadastradas no arquivo builds.json antes da realização do deploy.
2. As variáveis do Keycloak são obrigatórias: a aplicação falha no startup se algum placeholder de configuração não for substituído. Isso é proposital — evita subir uma solução com autenticação mal configurada.
3. A URI de redirecionamento cadastrada no client do Keycloak deve terminar em /signin-oidc (ex.: https://minhasolucao-d.nuvem.ti.embrapa.br/signin-oidc).

Para conhecer em detalhe o funcionamento e componentes da solução blazorpost acesse a seção Boilerplates. Se a sua solução for organizada em módulos de negócio, veja também a seção Modularização.

Executando localmente o projeto

Pré-requisitos

1. Editor Visual Studio Code instalado.
2. Docker e Compose instalados (Linux).
3. Caso esteja em ambiente Windows, ter o WSL instalado com as soluções docker e compose instaladas.
4. Caso opte por rodar fora do devcontainer, instale o SDK do .NET 10 (versão utilizada pelos boilerplates atuais).
5. Instale o Plugin C# Dev Kit da Microsoft localmente ou dentro do devcontainer, a depender da forma de trabalho escolhida.

Executando com Dev Container

Para desenvolver utilizando Dev Container, siga os passos abaixo:

1. Instale a extensão “Dev Containers” no Visual Studio Code:
   • Abra o VS Code
   • Pressione Ctrl+Shift+X para abrir a aba de extensões
   • Pesquise por “Dev Containers”
   • Instale a extensão “Dev Containers” da Microsoft
2. Configurar o Dev Container:
   • Pressione F1 ou Ctrl+Shift+P para abrir a paleta de comandos
   • Digite “Dev Containers: New Dev Container”
   • Selecione “C# (.NET)”
   • Selecione a opção “Additional Optional”
   • Escolha a versão adequada à sua solução Ex.: “.NET 10.0”
   • Na lista de “Features” adicionais, selecione:
     • “Docker (docker-outside-of-Docker)” (devcontainers verified)
   • Selecione “Keep Defaults” nas configurações
   • Clique em OK no próximo passo e aguarde a criação do Dev Container.

3. Instale o Plugin do C# Dev Kit dentro do Dev Container criado.

4. Faça o clone do projeto na pasta workspace dentro do Dev Container.

5. Siga as orientações a seguir para a configuração do banco de dados na solução.

Com BD Local

1. Solicite (ou crie, se você tiver acesso ao realm) um client OIDC no Keycloak para desenvolvimento, com a URI de redirecionamento http://localhost:5205/signin-oidc (ajuste a porta se você a tiver alterado). Anote a URL do realm (Authority), o ClientId e o ClientSecret.
2. Se a solução consome dados corporativos, obtenha a string de conexão do MongoDB do ETL e, se for o caso, as credenciais da API do Portal Embrapa para a foto do empregado.
3. Crie uma cópia dos arquivos “.env.example” e “.env.io.example” renomeando para “.env” e “.env.io” respectivamente e preencha os valores que porventura estejam faltando ou que você deseja substituir — em especial as variáveis KEYCLOAK_*, MONGO_* e EMBRAPA_PORTAL_*.

4. Gere o arquivo de configuração da solução através do terminal do VSCode e execute os seguintes comandos:

   Linux e Dev Container

    chmod +x scripts/generate-appsettings.sh
    ./scripts/generate-appsettings.sh
   

   Windows

    .\scripts\generate-appsettings.ps1
   

5. Execute o script de criação do banco local:

   Linux e Dev Container

    chmod +x scripts/start-db.sh
    ./scripts/start-db.sh
   

   Windows

    .\scripts\start-db.ps1
   

6. Na opção Run and Debug do VSCode, selecione a opção C# e depois escolha o profile de execução adequado para o seu ambiente Ex. HTTP.

Com BD Remoto

1. Solicite o client OIDC no Keycloak para o estágio desejado, conforme descrito acima.
2. Se a solução consome dados corporativos, obtenha a string de conexão do MongoDB do ETL.
3. Crie uma cópia dos arquivos “.env.example” e “.env.io.example” renomeando para “.env” e “.env.io” respectivamente e preencha os valores que porventura estejam faltando ou que você deseja substituir.

4. No arquivo .env, substitua os valores das variáveis de banco pelas informações do seu BD Remoto.

    DB_HOST=postgres:5432
    DB_NAME=blazorserverapp
    DB_PASS=Secret
    DB_USER=blazorserverapp_user
   

5. Gere o arquivo de configuração da solução através do terminal do VSCode e execute os seguintes comandos:

   Linux e Dev Container

    chmod +x scripts/generate-appsettings.sh
    ./scripts/generate-appsettings.sh
   

   Windows

    .\scripts\generate-appsettings.ps1
   

6. Na opção Run and Debug do VSCode, selecione a opção C# e depois escolha o profile de execução adequado para o seu ambiente Ex. HTTP.

Desenvolvendo com Hot Reload

Para o ciclo de desenvolvimento do dia a dia, a forma recomendada é executar a aplicação em modo watch e anexar o depurador quando precisar:

dotnet watch run

A aplicação fica disponível em http://localhost:5205. No VSCode, o mesmo pode ser feito por Ctrl+Shift+P → “Tasks: Run Task” → watch.

Para depurar, com a aplicação já rodando em watch, pressione F5 e escolha:

• “Debug (Attach to App)” — anexa automaticamente ao processo da aplicação;
• “Debug (Select Process)” — permite escolher manualmente o processo.

Os breakpoints funcionam normalmente e o Hot Reload continua ativo durante a depuração, preservando o estado da aplicação entre as mudanças de código.

Para encerrar o watch:

pkill -f "dotnet watch"

Validação antes de commitar. Os boilerplates não possuem projeto de testes automatizados: a validação é dotnet build sem erros mais a verificação manual em http://localhost:5205. Se a sua solução usa módulos, rode também os gates descritos na seção Modularização.