# 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*
