@polymorphism-tech/morph-spec 1.0.2 → 2.0.0

package/content/.morph/standards/dotnet10-migration.md

@@ -0,0 +1,494 @@
+# 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>`
+
+---
+
+## 📊 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*