@polymorphism-tech/morph-spec 3.2.0 → 4.2.0

package/stacks/blazor-azure/.morph/standards/dotnet10-migration.md

@@ -1,520 +0,0 @@
-# Guia de Migração .NET 9 → .NET 10
-
-> Atualização completa do MORPH-SPEC para .NET 10 com foco em produtividade e AI.
-
----
-
-## 📋 Checklist Rápido
-
-### 1. Atualizar TargetFramework
-
-```xml
-<!-- Antes (.csproj) -->
-<TargetFramework>net9.0</TargetFramework>
-
-<!-- Depois -->
-<TargetFramework>net10.0</TargetFramework>
-```
-
-### 2. Atualizar Packages
-
-```bash
-dotnet list package --outdated
-dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 10.0.0
-dotnet add package Microsoft.AspNetCore.Components.WebAssembly --version 10.0.0
-```
-
-### 3. Atualizar SDK
-
-```bash
-dotnet --version  # Verificar
-# Instalar .NET 10 SDK de https://dot.net
-```
-
-### 4. Build e Testes
-
-```bash
-dotnet clean
-dotnet build
-dotnet test
-```
-
----
-
-## 🚀 Breaking Changes Críticos
-
-### 1. Semantic Kernel → Agent Framework
-
-**ANTES (.NET 9 com Semantic Kernel):**
-```csharp
-using Microsoft.SemanticKernel;
-
-var builder = Kernel.CreateBuilder();
-builder.AddAzureOpenAIChatCompletion(...);
-var kernel = builder.Build();
-
-var prompt = kernel.CreateFunctionFromPrompt("Analyze this data...");
-var result = await kernel.InvokeAsync(prompt, new() { ["data"] = data });
-```
-
-**DEPOIS (.NET 10 com Agent Framework):**
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-var chatClient = new ChatClient(
-    model: "gpt-4o-mini",
-    credential: new ApiKeyCredential(apiKey),
-    endpoint: new Uri(endpoint)
-);
-
-var agent = chatClient.CreateAgent(
-    instructions: "Analyze the provided data...",
-    name: "DataAnalyzer"
-);
-
-var response = await agent.RunAsync($"Analyze this data: {data}");
-```
-
-**Ação obrigatória:** Reescrever todo código de AI para usar Agent Framework.
-
-### 2. ChatHistory → Threads
-
-**ANTES:**
-```csharp
-var history = new ChatHistory();
-history.AddUserMessage("Hello");
-var response = await kernel.InvokeAsync(function, new() { ["history"] = history });
-history.AddAssistantMessage(response.GetValue<string>());
-```
-
-**DEPOIS:**
-```csharp
-var agent = chatClient.CreateAgent(...);
-var thread = await agent.CreateThreadAsync();
-
-await thread.AddMessageAsync("Hello");
-var response = await agent.RunAsync(thread);
-// Histórico mantido automaticamente no thread
-```
-
-### 3. Plugins → Tools (Manual Registration)
-
-**ANTES (automático):**
-```csharp
-kernel.Plugins.AddFromObject(new OrderPlugin());
-```
-
-**DEPOIS (manual):**
-```csharp
-var agent = chatClient.CreateAgent(
-    instructions: "...",
-    tools: new[]
-    {
-        AgentTool.FromMethod(nameof(GetOrder), this),
-        AgentTool.FromMethod(nameof(CalculateDiscount), this)
-    }
-);
-```
-
----
-
-## ✨ Novas Features para Aproveitar
-
-### 1. State Persistence (Blazor)
-
-**Como usar:**
-```csharp
-@page "/counter"
-
-<button @onclick="Increment">Count: @Count</button>
-
-@code {
-    // ANTES
-    // private int _count = 0;
-
-    // AGORA - persiste automaticamente em pre-rendering
-    [PersistentState]
-    private int Count { get; set; } = 0;
-
-    private void Increment() => Count++;
-}
-```
-
-**Quando usar:** Componentes com estado que precisam sobreviver a pre-rendering ou circuit disconnections.
-
-### 2. Circuit Pause/Resume
-
-**Como usar:**
-```razor
-@inject IJSRuntime JS
-
-@code {
-    protected override async Task OnAfterRenderAsync(bool firstRender)
-    {
-        if (firstRender)
-        {
-            await JS.InvokeVoidAsync("setupCircuitPause");
-        }
-    }
-}
-```
-
-```javascript
-// wwwroot/app.js
-function setupCircuitPause() {
-    document.addEventListener('visibilitychange', () => {
-        if (document.hidden) {
-            Blazor.pauseCircuit();  // Libera recursos do servidor
-        } else {
-            Blazor.resumeCircuit(); // Restaura estado
-        }
-    });
-}
-```
-
-**Quando usar:** Aplicações com muitos usuários simultâneos para otimizar recursos.
-
-### 3. Passkeys/WebAuthn
-
-**Como usar:**
-```bash
-# Novo projeto
-dotnet new blazor --auth Individual -o MyApp
-
-# Projeto existente
-dotnet aspnet-codegenerator identity --useDefaultUI --files "Account.Manage.Passkeys;Account.Login"
-```
-
-**Quando usar:** Sempre que possível para melhor segurança.
-
-### 4. Vector Search
-
-**Como usar:**
-```csharp
-// Entidade
-public class Document
-{
-    public int Id { get; set; }
-    public string Content { get; set; } = null!;
-    public ReadOnlyMemory<float> Embedding { get; set; }
-}
-
-// DbContext
-modelBuilder.Entity<Document>()
-    .Property(d => d.Embedding)
-    .HasColumnType("vector(1536)");
-
-// Query
-var results = await _context.Documents
-    .Select(d => new {
-        Document = d,
-        Distance = EF.Functions.VectorDistance(d.Embedding, queryVector, DistanceFunction.Cosine)
-    })
-    .OrderBy(r => r.Distance)
-    .Take(5)
-    .ToListAsync();
-```
-
-**Quando usar:** RAG, busca semântica, recomendações.
-
----
-
-## 🎯 C# 14 Features
-
-### 1. Field-Backed Properties
-
-**ANTES:**
-```csharp
-private string _name = "";
-public string Name
-{
-    get => _name;
-    set => _name = value?.Trim() ?? "";
-}
-```
-
-**AGORA:**
-```csharp
-public string Name
-{
-    get => field;
-    set => field = value?.Trim() ?? "";
-}
-// 'field' é keyword contextual para o backing field
-```
-
-### 2. Null-Conditional Assignment
-
-**ANTES:**
-```csharp
-if (customer != null)
-{
-    customer.Name = "New Name";
-}
-```
-
-**AGORA:**
-```csharp
-customer?.Name = "New Name";
-```
-
-### 3. Partial Constructors
-
-```csharp
-public partial class Order
-{
-    public partial Order(int customerId); // Declaração
-}
-
-// Outra parte do partial
-public partial class Order
-{
-    public partial Order(int customerId)  // Implementação
-    {
-        CustomerId = customerId;
-        CreatedAt = DateTime.UtcNow;
-    }
-}
-```
-
----
-
-## ⚡ Performance Wins Automáticos
-
-### Apenas fazer upgrade gera melhorias:
-
-| Área | Melhoria | Sem código |
-|------|----------|------------|
-| **Blazor WebAssembly rendering** | 20% mais rápido | ✅ |
-| **Hot reload** | 10x mais rápido | ✅ |
-| **Response times** | 49% mais rápido (vs .NET 8) | ✅ |
-| **GC overhead** | Reduzido (stack allocation) | ✅ |
-
-**Ação:** Apenas compile em .NET 10 e rode benchmarks.
-
----
-
-## 🔧 Migração Passo a Passo
-
-### Passo 1: Preparação (1 dia)
-
-```bash
-# 1. Criar branch
-git checkout -b upgrade-dotnet10
-
-# 2. Backup do banco
-# (Azure SQL: export bacpac)
-
-# 3. Atualizar SDK global
-dotnet --version
-
-# 4. Atualizar ferramentas
-dotnet tool update --global dotnet-ef
-```
-
-### Passo 2: Atualizar Projetos (2-3 dias)
-
-```bash
-# Para cada .csproj:
-# 1. Mudar TargetFramework
-# 2. Atualizar packages
-dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 10.0.0
-dotnet add package Microsoft.AspNetCore.Components.WebAssembly --version 10.0.0
-
-# 3. Build incremental
-dotnet build --no-incremental
-```
-
-### Passo 3: Migrar AI (3-5 dias)
-
-**Priorizar:**
-1. Listar todos os usos de Semantic Kernel
-2. Reescrever um agent de cada vez
-3. Testar isoladamente
-4. Deployar incrementalmente
-
-**Template de migração:**
-```csharp
-// ANTES
-var kernel = ...;
-var function = kernel.CreateFunctionFromPrompt(...);
-var result = await kernel.InvokeAsync(function, args);
-
-// DEPOIS
-var agent = chatClient.CreateAgent(instructions: ..., name: ...);
-var response = await agent.RunAsync(prompt);
-```
-
-### Passo 4: Adicionar Features (1-2 dias)
-
-```bash
-# Passkeys
-dotnet aspnet-codegenerator identity --files "Account.Manage.Passkeys"
-
-# Vector Search (se aplicável)
-dotnet ef migrations add AddVectorSearch
-dotnet ef database update
-```
-
-### Passo 5: Testes (2-3 dias)
-
-```bash
-# Unit tests
-dotnet test
-
-# Integration tests
-dotnet test --filter Category=Integration
-
-# E2E tests (Playwright)
-# ...
-
-# Performance tests
-dotnet run --configuration Release
-# Comparar com baseline .NET 9
-```
-
-### Passo 6: Deploy (1 dia)
-
-```bash
-# 1. Deploy staging
-az containerapp update --name ca-myapp-staging --image myapp:net10
-
-# 2. Smoke tests
-curl https://myapp-staging.azurecontainerapps.io/health
-
-# 3. Deploy produção
-az containerapp update --name ca-myapp-prod --image myapp:net10
-
-# 4. Monitorar Application Insights
-```
-
----
-
-## 🐛 Problemas Comuns
-
-### Erro: "Microsoft.Agents.AI not found"
-
-**Solução:**
-```bash
-dotnet add package Microsoft.Agents.AI --version 1.0.0
-```
-
-### Erro: "vector type not supported"
-
-**Causa:** SQL Server antigo.
-
-**Solução:** Use Azure SQL Database ou SQL Server 2022+.
-
-### Erro: "Hot reload not working"
-
-**Solução:**
-1. Atualize Visual Studio 2026 Preview
-2. Ou use `dotnet watch` no CLI
-
-### Performance não melhorou
-
-**Verificar:**
-1. Compilou em Release? `dotnet build -c Release`
-2. Rodando em produção (não dev server)?
-3. Habilitou ReadyToRun? `<PublishReadyToRun>true</PublishReadyToRun>`
-
-### Erro: blazor.web.js 404 em Container/Docker
-
-**Erro:**
-```
-GET /_framework/blazor.web.js net::ERR_ABORTED 404
-```
-
-**Causa:** .NET 10 não embute `blazor.web.js` por padrão em containers.
-
-**Solução:** Adicionar no `.csproj`:
-
-```xml
-<!-- .NET 10: OBRIGATÓRIO para Blazor Server em Docker -->
-<PropertyGroup>
-  <RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>
-</PropertyGroup>
-```
-
-**Tentativas que NÃO funcionam:**
-- ❌ `<PublishStaticWebAssets>true</PublishStaticWebAssets>`
-- ❌ `<StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode>`
-- ❌ Copiar `blazor.web.js` do SDK manualmente
-- ❌ Adicionar referência ao `Microsoft.AspNetCore.Components.Web`
-
-**Contexto:** Este é um breaking change não documentado no .NET 10. A propriedade `RequiresAspNetWebAssets` força o SDK a incluir os assets do ASP.NET Core no publish.
-
----
-
-## 📊 Estimativa de Esforço
-
-| Projeto | Dias | Complexidade |
-|---------|------|--------------|
-| Simples (sem AI) | 2-3 | Baixa |
-| Médio (1-2 agents) | 5-7 | Média |
-| Complexo (5+ agents, vector search) | 10-15 | Alta |
-
-**Fatores:**
-- Quantidade de código Semantic Kernel
-- Testes existentes
-- Complexidade de agents
-- Features novas adotadas
-
----
-
-## ✅ Definition of Done
-
-- [ ] Todos .csproj com `net10.0`
-- [ ] Todos packages atualizados
-- [ ] Zero warnings de build
-- [ ] Semantic Kernel removido
-- [ ] Agent Framework funcionando
-- [ ] Testes passando (>95% coverage mantido)
-- [ ] Deploy em staging OK
-- [ ] Performance igual ou melhor
-- [ ] Documentação atualizada
-- [ ] Equipe treinada
-
----
-
-## 📚 Recursos
-
-| Recurso | URL |
-|---------|-----|
-| .NET 10 Release Notes | [aka.ms/dotnet10](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-10) |
-| Agent Framework Docs | [learn.microsoft.com/agent-framework](https://learn.microsoft.com/agent-framework/) |
-| Breaking Changes | [aka.ms/dotnet10-breaking](https://learn.microsoft.com/dotnet/core/compatibility/10.0) |
-| Migration Guide (oficial) | [aka.ms/migrate-to-dotnet10](https://learn.microsoft.com/dotnet/core/porting/) |
-
----
-
-## 🎓 Treinamento da Equipe
-
-### Sessões Recomendadas
-
-1. **.NET 10 Overview** (1h)
-   - Performance improvements
-   - Breaking changes
-   - New features
-
-2. **Agent Framework Deep Dive** (2h)
-   - Migração de Semantic Kernel
-   - Hands-on: criar agent do zero
-   - Tools e function calling
-
-3. **Blazor .NET 10** (1h)
-   - State persistence
-   - Circuit management
-   - Performance tips
-
-4. **Vector Search + RAG** (2h)
-   - EF Core 10 vectors
-   - Embedding generation
-   - RAG pattern completo
-
-**Total:** 6h de treinamento
-
----
-
-*MORPH-SPEC by Polymorphism Tech*