Devprime 9

Este guia aborda os pontos essenciais para realizar a atualização da versão 8 para a 9 da Devprime Platform, aproveitando o .NET 9 SDK. Incluímos instruções detalhadas sobre alterações no Dockerfile, métodos, configurações e muito mais.

Novidades: Microsoft OpenAPI / Swagger / Scalar

O .NET 9 introduziu a biblioteca Microsoft.AspNetCore.OpenApi, que altera a abordagem tradicional de documentação de APIs. Agora, é possível utilizar ferramentas como Swagger e Scalar diretamente com esta nova biblioteca.

Ferramentas Disponíveis

• Microsoft.AspNetCore.OpenApi
• Swashbuckle.AspNetCore.Swagger
• Scalar.AspNetCore

Atualizações em Métodos no Arquivo App.cs

A tabela abaixo destaca as mudanças nos métodos da Devprime:

Atualizações no appsettings.json

Adicione ou revise as chaves abaixo:

Exemplo de configuração:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

"DevPrime_Web": {
    "Url": "https://localhost:5001;http://localhost:5000",
    "Enable": "true",
    "EnableOpenApi": "true",
    "EnableSwagger": "true",    
    "EnableScalar": "true",
    "PostSuccess": "201",
    "PostFailure": "500",
    "GetSuccess": "200",
    "GetNotFound": "404",
    "GetFailure": "500",
    "PatchSuccess": "200",
    "PatchFailure": "500",
    "PutSuccess": "200",
    "PutFailure": "500",
    "DeleteSuccess": "200",
    "DeleteFailure": "500",
    "EnableWebLegacy": "false",
    "EnableStaticFiles": "true",
    "ShowHttpRequests": "false",
    "ShowBadRequestDetails": "false"
  },

Passo a Passo para Atualização

1. Preparação do Ambiente

a. Instale o .NET SDK 9
Baixar .NET SDK

b. Atualize o Devprime CLI para a versão 9.0.4 ou superior

1

dotnet tool update --global Devprime.cli

c. Autentique no CLI atualizado

1

dp auth

2. Atualizações no Projeto

a. Atualize os Arquivos .csproj

Modifique o TargetFramework para net9.0 utilizando o Visual Studio Code. Abra a pasta do projeto no VS Code e, no menu Edit > Replace in Files, localize os itens abaixo e realize a substituição.

b. Atualize o Stack da Devprime

Atualização dos componentes da Devprime para a versão 9.0 no arquivo .csproj e da nova chave de License no arquivo appsettings.json.

Execute o comando na pasta do seu projeto:

1

dp stack

c. Atualize o Dockerfile

Atualize as referências para o .NET 9, altere o arquivo Dockerfile para utilizar a imagem docker com base no .NET SDK 9. Você precisa localizar o ASP.NET e depois o SDK para realizar a atualização.

• Abra pelo Visual Studio Code na pasta do seu projeto

1

code Dockerfile

• Localize a referência aspnet e altere para o exemplo:

1

FROM mcr.microsoft.com/dotnet/aspnet:9.0.10-noble AS base

• Localize a referência sdk e altere para o exemplo:

1

FROM mcr.microsoft.com/dotnet/sdk:9.0.306-noble AS build

c. Atualize o App.cs

Com a introdução dos novos métodos (AddOpenApi, AddSwagger, AddScalar e seus equivalentes Use*), configure o arquivo App.cs para utilizar os recursos desejados. Seguem as orientações detalhadas:

Abra pelo Visual Studio Code na pasta do seu projeto

1

code src/App/App.cs

Passo 1: No bloco builder
O exemplo abaixo mostra a adição dos serviços OpenAPI, Swagger e Scalar. Você pode utilizar
o Swagger e Scalar juntos.

1
2
3

DpApp.AddOpenApi(builder.Services); // Add OpenAPI Services
DpApp.AddSwagger(builder.Services); // Add Swagger Services
DpApp.AddScalar(builder.Services);  // Add Scalar Services 

Passo 2: No bloco app
Configure os serviços no bloco app. A ordem recomendada é UseOpenApi, seguido por UseSwagger ou UseScalar.

1
2
3

DpApp.UseOpenApi(app); // Enable OpenApi
DpApp.UseSwagger(app); // Enable Swagger
DpApp.UseScalar(app);  // Enable Scalar

Passo 3: Exemplo completo do arquivo App.cs
O App.cs pode ser configurado para utilizar OpenAPI, Swagger e Scalar simultaneamente conforme
o exemplo abaixo do microsserviço order.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMvc(o =>
{
    o.EnableEndpointRouting = false;
});

builder.Services.AddScoped<IExtensions, Extensions>();
builder.Services.AddScoped<IEventStream, EventStream>();
builder.Services.AddScoped<IEventHandler, Application.EventHandlers.EventHandler>();

await new DpApp(builder).Run("order", (app) =>
{
    app.UseRouting();
    
    app.UseAuthentication(); // Enable Authentication

    DpApp.UseOpenApi(app); // Enable OpenApi
    DpApp.UseSwagger(app); // Enable Swagger
    DpApp.UseScalar(app);  // Enable Scalar


    app.UseAuthorization(); // Enable Authorization

    app.MapControllerRoute(
       name: "default",
       pattern: "{controller=Home}/{action=Index}/{id?}");
}, (builder) =>
{
    DpApp.AddDevPrime(builder.Services); // Enable Foundation

    DpApp.AddOpenApi(builder.Services); // Add OpenAPI Services
    DpApp.AddSwagger(builder.Services); // Add Swagger Services
    DpApp.AddScalar(builder.Services);  // Add Scalar Services

    DpApp.AddDevPrimeSecurity(builder.Services); // Add Security Services
});

Observações:

• Tendências de mercado: O uso do Scalar está se tornando popular e pode substituir o Swagger em muitos casos. Você pode configurar ambos inicialmente e desativar um deles conforme necessário.
• Compatibilidade garantida: Caso você não faça nenhuma alteração no arquivo App.cs, o comportamento padrão não será quebrado, mas é recomendável adotar os novos métodos para aproveitar todos os benefícios.

d. Urls do OpenApi / Swagger / Scalar

A Devprime irá, por padrão, ativar URLs padrão para os serviços OpenApi, Swagger e Scalar, caso estejam ativados, conforme os endereços abaixo. Esses endereços também irão variar conforme a porta TCP local utilizada no seu microsserviço e o nome do projeto.

Exemplo: Para um projeto chamado order executado na porta TCP 5001:

3. Atualização da Interface Web (Opcional)

Edite o arquivo index.cshtml para incluir links para Swagger, Scalar e OpenAPI:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

@page
@model DevPrime.Web.IndexModel
@{
    ViewData["Title"] = DevPrime.Stack.Foundation.Setup.AppName;
}

<div style='text-align:center;padding:10px;margin:10px;color:#512da8'>
    <h1>Welcome to @DevPrime.Stack.Foundation.Setup.AppName! </h1>
    <h2>Powered by Devprime</h2>
    <p>Microservice Id : @DevPrime.Stack.Foundation.Setup.AppID</p>
   
    <p>Try: 
        [<a href="~/openapi/@(DevPrime.Stack.Foundation.Setup.AppName)/
        @(DevPrime.Stack.Foundation.Setup.AppVersion).json">OpenApi</a>]
        [<a href='~/swagger/index.html'>Swagger</a>]
        [<a href="~/scalar/@DevPrime.Stack.Foundation.Setup.AppName">Scalar</a>]
    </p>
</div>

4. Atualização nas configurações do yaml no Kubernetes (Opcional)

É importante lembrar que durante esse roteiro nós incluimos novas chavaes de configuração e você pode aleterar manualmente e/ou utilizar o exportador da Devprime CLI para exportar a configuração atualizada:

Checklist importante
a) Novos parametros de configuração: (EnableSwagger, EnableScalar, EnableOpenApi, GetNotFound).
b) Nova chave de License que foi aplicada no seu appsettings.json e precisa ser atualizada no yaml de produção.
c) O comando dp export kubernetes já exporta a nova chave de License.

Para um exemplo completo execute o comando na pasta do projeto:

1

dp export Kubernetes

Conclusão

Seguindo este guia, sua aplicação estará pronta para utilizar as novidades da Devprime 9 e do .NET 9. Para dúvidas, entre em contato com o suporte técnico.