> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/conceitos/readme/sdk.md).

# SDK

O SDK do skail é o que você adiciona ao seu projeto para escrever funções duráveis. 

Ele resolve três responsabilidades:

1. Oferece os atributos que identificam qual código é orquestrador durável.
2. Expõe o tipo `SkailTask`, que se integra ao `async/await` nativo do — você escreve código assíncrono normal e o SDK instrumenta a execução para que o runtime possa hibernar e retomar em qualquer `await`.
3. Inclui um analyzer Roslyn que valida, em tempo de compilação, regras que a skail precisa respeitar para o modelo durável funcionar corretamente.

Além do pacote central, há um pacote dedicado a testes (`Skail.Platform.Runtime.Testing`) para escrever unit tests das funções duráveis sem depender de infraestrutura externa.

### Atributos (Decorators)

Dois atributos definem o comportamento do seu código dentro da skail.

#### \[[SkailFunction](/funcionalidades/sdk/skailfunction.md)]

Marca um método como orquestrador durável. Um método anotado com `[SkailFunction]` vive no runtime da skail: sua execução é persistida ao longo de hibernações, sobrevive a quedas de processo, e seu progresso é memoizado passo a passo. 

#### \[[SkailCommand](/funcionalidades/sdk/skailcommand.md)]

Marca um método como efeito colateral memoizado. Um `[SkailCommand]` é a unidade de escrita confiável: cada chamada é registrada junto com seu resultado, de modo que durante uma retomada o comando não é executado novamente — o runtime devolve o resultado guardado. 

### SkailTask

`SkailTask` é a raiz do SDK em tempo de execução. Ele se comporta como um `Task` do .NET — você usa `await`, trata exceções com `try/catch`, encadeia operações normalmente — mas é implementado sobre um `AsyncMethodBuilder` customizado que permite ao runtime hibernar a execução em qualquer `await`.

Do ponto de vista de quem escreve o código, a única mudança em relação a uma aplicação comum é trocar `Task` por `SkailTask` nas assinaturas:

```csharp
// versão não-durável
public async Task ProcessarPedido(Guid pedidoId) { ... }

// versão durável
[SkailFunction]
public async SkailTask ProcessarPedido(Guid pedidoId) { ... }
```

Todas as combinações normais de `async/await` continuam valendo — LINQ sobre coleções de `SkailTask`, exceções tipadas, `using`, `try/finally`, delegados. A recomendação é não misturar `Task` e `SkailTask` no mesmo fluxo durável, porque isso removeria a garantia de retomada para as partes não-`SkailTask`.

#### Primitivas estáticas

`SkailTask` expõe as primitivas de orquestração como métodos estáticos:

```csharp
await SkailTask.Delay(TimeSpan.FromHours(2));
await SkailTask.DelayMinutes(15);
await SkailTask.WhenAll(tarefa1, tarefa2);
var primeira = await SkailTask.WhenAny(tarefa1, tarefa2);
await SkailTask.WaitForEvent<T>("NOME", instanceId);
await SkailTask.FireEvent("NOME", instanceId, payload);
```

Cada uma é detalhada nas seções específicas deste guia.

### Analyzer

O SDK inclui um analyzer Roslyn (`Skail.Platform.Analyzer`) que roda na compilação do seu projeto e aponta problemas que a skail não consegue resolver em tempo de execução. Entre outras coisas, ele identifica:

* uso de `Task` em vez de `SkailTask` em assinaturas de `[SkailFunction]` e `[SkailCommand]`;
* operações não-determinísticas (como `DateTime.Now`, `Guid.NewGuid()`, `Random`) chamadas fora de `[SkailCommand]`, que quebrariam o replay;
* chamadas a `[SkailCommand]` feitas fora de contexto de execução durável;
* assinaturas inválidas de funções e comandos.

O analyzer transforma erros que seriam sutis em tempo de execução em avisos ou erros de compilação claros, antes do código rodar.

### Posicionamento no conjunto da solução

O SDK é onde você **escreve** código skail. Ele não é um serviço em execução. O que transforma esse código instrumentado em execuções duráveis é o [Runtime](/conceitos/readme/runtime.md), com quem o SDK se comunica por baixo, sem que o desenvolvedor precise lidar com isso diretamente.

Na prática:

* anota seus métodos com `[SkailFunction]` e `[SkailCommand]`;
* usa `SkailTask` nas assinaturas;
* compila e publica sua aplicação normalmente;
* a persistência, o agendamento e o replay ficam por conta do Runtime.