# SkailFunction

É a forma de marcar um método do seu código como uma etapa de orquestração dentro do skail. Em vez de ser apenas um método C# executado de ponta a ponta em memória, ele passa a rodar com controle de estado, retomada de execução e coordenação de etapas assíncronas de longa duração.

Na prática, isso permite que o desenvolvedor escreva fluxos de negócio no próprio código .NET, usando uma estrutura familiar, mas com capacidades extras do skail, como persistência do progresso, reexecução segura após falhas, espera por eventos externos e encadeamento de outras operações sem precisar montar manualmente toda a infraestrutura de mensageria, controle de estado e recuperação.

### Como a `SkailFunction` atua no runtime skail

Ao marcar um método com `SkailFunction`, esse método deixa de ser tratado apenas como uma chamada local do código e passa a ser reconhecido pela skail como um ponto de entrada de execução do processo. Em outras palavras, ele se torna um **entry point** de orquestração: é a partir dele que a plataforma inicia, retoma e acompanha o processo de negócio.

Esse comportamento é o que permite à skail adicionar capacidades de execução durável ao código da aplicação. Quando a função entra em execução, a plataforma passa a controlar o histórico, registrar o progresso de cada etapa e garantir que o fluxo possa continuar com segurança mesmo em cenários de falha, reinício ou espera prolongada.

Na prática, isso traz benefícios importantes para o desenvolvimento e para a operação:

* O método passa a representar formalmente o início de um fluxo orquestrado.
* A execução deixa de depender apenas do ciclo de vida do processo em memória.
* O progresso do fluxo pode ser retomado sem que a lógica de negócio precise ser reimplementada.
* A aplicação ganha um modelo mais seguro para processos longos, distribuídos e assíncronos.

### Observabilidade da `SkailFunction`

Além de transformar o método em um entry point de orquestração, a `SkailFunction` também passa a contar com recursos de observabilidade oferecidos pela skail. Isso significa que a execução do fluxo não fica restrita ao código da aplicação: ela também pode ser acompanhada operacionalmente pela plataforma.

A observabilidade fornecida pela skail inclui, principalmente:

* **Rastreamento da execução** Cada execução da `SkailFunction` gera informações que permitem acompanhar o caminho percorrido pelo fluxo, incluindo o início da execução, chamadas relacionadas, retomadas e encadeamentos entre etapas.
* **Correlação entre etapas** Quando a função chama outras operações skail da solução, a plataforma mantém a correlação entre essas execuções, facilitando o entendimento do fluxo completo e a análise de dependências entre etapas.
* **Visibilidade sobre falhas e retomadas** Como o skail controla o ciclo de vida da execução, também é possível identificar falhas, tentativas de reprocessamento e retomadas de processamento, o que simplifica diagnóstico e suporte.
* **Acompanhamento operacional** A execução pode ser acompanhada no monitor disponível no portal do skail (<https://app.skailhq.com/>), permitindo visualizar o andamento da função, inspecionar o comportamento do fluxo e apoiar atividades de operação, troubleshooting e auditoria.

Esse modelo reduz significativamente o esforço de instrumentação manual. Em vez de depender apenas de logs locais ou de implementações customizadas de rastreamento, a aplicação passa a operar com um nível de visibilidade mais adequado para cenários críticos e distribuídos.

### Como marcar um método como `SkailFunction`

Para que um método seja tratado pela skail como uma função de orquestração, ele deve ser decorado com o atributo `SkailFunction`.

Exemplo básico:

```csharp
[SkailFunction]
public async SkailTask ProcessarPedido(Guid pedidoId)
{
    // lógica de negócio
}
```

Ao aplicar esse atributo, o método passa a ser reconhecido pela plataforma como parte do modelo de execução da skail.

#### Requisitos recomendados para uso

Na prática, uma `SkailFunction` deve seguir o padrão esperado pela plataforma:

* Ser um método da aplicação marcado com o atributo `SkailFunction`.
* Utilizar `SkailTask` ou `SkailTask<T>` como tipo de retorno.

### Atributos disponíveis no decorator `SkailFunction`

O atributo `SkailFunction` aceita parâmetros que permitem personalizar o comportamento da função dentro da skail.

#### Uso padrão

```csharp
[SkailFunction]
public async SkailTask ProcessarPedido(Guid pedidoId)
{
}
```

Nesse formato, a plataforma utiliza a configuração padrão da função, incluindo a convenção de nome e a política padrão de tentativas (retry).

#### `skailMethodName`

Permite definir explicitamente o nome lógico pelo qual a função será identificada pela skail.

Exemplo:

```csharp
[SkailFunction(skailMethodName: "pedido/processar/v1")]
public async SkailTask ProcessarPedido(Guid pedidoId)
{
}
```

Esse atributo é útil quando se deseja:

* Padronizar a identificação das funções na solução.
* Controlar versionamento de contratos de execução.
* Tornar o nome da função mais estável e independente do nome interno do método no código.
* Organizar melhor fluxos expostos ou integrados com outros componentes da plataforma.

Quando `skailMethodName` não é informado, a skail gera o identificador da função com base no contexto da workload \[link explicando o que é workload] e no nome do método.

#### `retryCount`

Permite definir a quantidade máxima de tentativas de reentrega associadas à execução daquela função.

Exemplo:

```csharp
[SkailFunction(retryCount: 3)]
public async SkailTask ProcessarPedido(Guid pedidoId)
{
}
```

Esse atributo é importante para ajustar a resiliência da execução conforme a criticidade e o comportamento esperado pelas regras de negócio. Em cenários apropriados, ele permite equilibrar:

* tolerância a falhas transitórias,
* previsibilidade operacional,
* controle sobre reprocessamentos automáticos.

Quando não é informado,  15 é utilizado como valor padrão.

#### Exemplo com múltiplos parâmetros

```csharp
[SkailFunction(skailMethodName: "pedido/processar/v1", retryCount: 5)]
public async SkailTask ProcessarPedido(Guid pedidoId)
{
}
```

Nesse caso, a função passa a ter um identificador explícito dentro da skail e uma política de tentativas ajustada para o cenário do processo.

### Boas práticas de uso

Para obter o melhor resultado com `SkailFunction`, recomenda-se:

* Usar a função como ponto de orquestração do processo, e não como bloco único de processamento.
* Dar nomes claros e estáveis às funções quando elas representarem fluxos importantes da solução.
* Definir `retryCount` de forma coerente com o comportamento esperado do negócio.
* Aproveitar a observabilidade da skail para monitorar a execução desde o início do desenvolvimento até a operação em produção.

Com isso, a `SkailFunction` deixa de ser apenas uma anotação no código e passa a atuar como um mecanismo central de estruturação, execução e acompanhamento de ponta a ponta das regras de negócio dentro do skail.


---

# 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/skailfunction.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.