# SkailCommand

À medida que você escreve a lógica de negócio da sua aplicação, alguns métodos fazem algo que **não pode ser perdido**: persistir um pedido, movimentar um saldo, registrar uma transação. São operações que, se interrompidas no meio por uma falha de infra ou reinicialização, precisam ser concluídas — não ignoradas.

É exatamente aí que você usa `[SkailCommand]`.

```csharp
[SkailCommand]
public async SkailTask RegistrarPedido(Pedido pedido)
{
    await _repositorio.SalvarAsync(pedido);
    await _estoque.ReservarAsync(pedido.Itens);
}
```

Você continua escrevendo o método como escreveria qualquer outro. A diferença é que a skail garante que, se algo interromper a execução antes do fim, o método será retomado automaticamente — sem que você precise pensar nisso.

#### Quando usar

Use `[SkailCommand]` quando o método representa **uma ação que precisa acontecer de verdade**: gravar, movimentar, enviar, reservar. 

Um bom critério: se o usuário ou o sistema ficaria em um estado inconsistente caso aquele método fosse interrompido e não retomado OU é um código não determinístico, ele é um bom candidato para `[SkailCommand]`.

#### Como declarar

O método precisa ser `async`, retornar `SkailTask` ou `SkailTask<T>`, ser `public` e não ser `static`. O compilador vai apontar qualquer desvio disso antes mesmo de você rodar a aplicação.

```csharp
[SkailCommand]
public async SkailTask<Fatura> EmitirFatura(Pedido pedido)
{
    var fatura = _faturaService.Gerar(pedido);
    await _repositorio.SalvarAsync(fatura);
    return fatura;
}
```

#### Retentativas

Por padrão, se o método lançar uma exceção, o skail o reexecuta até **5 vezes** antes de considerar a operação como falha. Você pode ajustar esse número quando necessário:

```csharp
[SkailCommand(retryCount: 10)]
public async SkailTask EnviarNotificacaoFiscal(string destinatario)
{
    await _notificacaoService.EnviarAsync(destinatario);
}
```

Defina um `retryCount` maior para operações que dependem de serviços externos com instabilidade conhecida, e menor (ou `0`) quando o seu código já trata a idempotência e uma única tentativa é suficiente.

#### Observabilidade

Cada execução de um `SkailCommand` gera automaticamente informações da execução: status, número de tentativas realizadas, identificador da tarefa e da raiz do fluxo. Você não precisa instrumentar nada — isso acontece pela própria skail.

No [portal do skail](https://app.skailhq.com/), na seção **Monitor**, você consegue acompanhar o estado de cada command: se completou com sucesso, se está em retentativa, se falhou após esgotar as tentativas. Isso é especialmente útil quando uma operação critica para de responder e você precisa entender exatamente em qual ponto ela está.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.skailhq.com/funcionalidades/sdk/skailcommand.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.