> 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/construir/configurar-e-hospedar/como-hospedar-worker-service-asp.net-core-container-kubernetes-azure.md).

# Como hospedar: Worker Service, ASP.NET Core, container, Kubernetes, Azure

O runtime do skail roda dentro do seu processo .NET e precisa de três coisas: `builder.UseSkail()`, `[assembly: VisibleToSkailPlatform]` e as variáveis de ambiente obrigatórias. Este guia parte do Worker Service e mostra só o que muda em cada modelo de hospedagem.

## Pré-requisitos

.NET 8 ou superior, um environment criado no portal (chave, namespace e endereço do skail anotados) e um workload com `nome:versao` definido. As quatro variáveis obrigatórias estão em [Como configurar o runtime](/construir/configurar-e-hospedar/como-configurar-o-runtime.md).

## Worker Service (caso base)

O runtime busca trabalho no skail; é a sua aplicação que chama o skail, nunca o contrário. A aplicação não recebe chamadas de entrada, então não precisa expor porta HTTP: um Worker Service é o encaixe natural.

```xml
<!-- Faturamento.Worker.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Worker">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Skail.Platform.Runtime" Version="2.2.*" />
  </ItemGroup>
</Project>
```

```csharp
// Program.cs
using Microsoft.Extensions.Hosting;
using Skail.Platform.Runtime.Hosting;
using Skail.Platform.Runtime.Standard;

[assembly: VisibleToSkailPlatform]

var builder = Host.CreateApplicationBuilder(args);

// seus serviços: DbContext, IHttpClientFactory, etc.
builder.UseSkail();

await builder.Build().RunAsync();
```

`UseSkail()` registra o `IHostedService` que busca trabalho no skail e registra como transient toda classe que contém métodos decorados, então a injeção por construtor funciona normalmente. Chame `UseSkail()` uma única vez por processo; a segunda chamada lança "The Builder Factory can only be registered once!".

O pacote `Skail.Platform.Runtime` traz por dependência o `Skail.Platform.Runtime.Build`, que faz o IL weaving durante o `dotnet build`. Nada a configurar, mas o build precisa acontecer com esse pacote presente (vale para o build em container, adiante).

O que você deve ver: a aplicação sobe sem erro e fica em espera por trabalho; o primeiro trigger aparece como execução no Monitor.

## ASP.NET Core

Todos os exemplos oficiais usam `Host.CreateApplicationBuilder`, e é esse o arranjo que recomendamos, em dois processos: a API web (controllers, webhooks, telas) em um projeto ASP.NET Core que dispara funções e eventos pela API HTTP, e a aplicação skail em um Worker Service. Os dois compartilham uma biblioteca com os DTOs e as constantes de nome de evento. Essa separação também escala melhor: a API escala por requisições, a aplicação skail escala por execuções.

```
Faturamento.sln
  Faturamento.Contratos/     DTOs, records, class Eventos com as constantes
  Faturamento.Api/           ASP.NET Core: POST /trigger e /api/v1/fire via HttpClient "skail"
  Faturamento.Worker/        Worker Service: [SkailFunction] e [SkailCommand], UseSkail()
```

Como a API chama o skail está em [Como disparar uma função pela API HTTP](/construir/escrever-fluxos/como-disparar-uma-funcao-pela-api-http.md).

## Container

Build em duas etapas. O `dotnet publish` roda na imagem do SDK, onde o IL weaving acontece; a imagem final só precisa do runtime .NET.

```dockerfile
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish Faturamento.Worker/Faturamento.Worker.csproj -c Release -o /app

FROM mcr.microsoft.com/dotnet/runtime:8.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "Faturamento.Worker.dll"]
```

Se o feed do pacote exigir credencial, passe-a ao build como segredo, nunca em um `nuget.config` versionado.

Configuração por variável, nunca na imagem:

```bash
docker run --rm \
  -e SKAIL_WORKLOAD=faturamento:v1.0.0 \
  -e SKAIL_NAMESPACE=SEU_NAMESPACE \
  -e SKAIL_KEY=SUA_SKAIL_KEY \
  -e SKAIL_SIDECAR=<endereço do skail> \
  registry.exemplo.com/faturamento-worker:1.0.0
```

Ou com `--env-file skail.env`, mantendo o arquivo fora do repositório.

## Kubernetes

Um `Deployment` sem `Service`: o worker não recebe tráfego. Chave e namespace vêm de um `Secret`; o restante em `env`.

```bash
kubectl create secret generic skail-faturamento \
  --from-literal=key=SUA_SKAIL_KEY \
  --from-literal=namespace=SEU_NAMESPACE
```

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: faturamento-worker-v1-0-0
spec:
  replicas: 2
  selector:
    matchLabels:
      app: faturamento-worker
      versao: v1-0-0
  template:
    metadata:
      labels:
        app: faturamento-worker
        versao: v1-0-0
    spec:
      containers:
        - name: worker
          image: registry.exemplo.com/faturamento-worker:1.0.0
          env:
            - name: SKAIL_WORKLOAD
              value: "faturamento:v1.0.0"
            - name: SKAIL_SIDECAR
              value: "<endereço do skail>"
            - name: SKAIL_NAMESPACE
              valueFrom:
                secretKeyRef:
                  name: skail-faturamento
                  key: namespace
            - name: SKAIL_KEY
              valueFrom:
                secretKeyRef:
                  name: skail-faturamento
                  key: key
```

A alavanca de vazão é `replicas`: mais processos rodando o mesmo workload, mais execuções em andamento ao mesmo tempo. Comece com poucas réplicas e suba conforme o sistema downstream aguentar. O nome do `Deployment` carrega a versão de propósito: no deploy de uma nova versão, o `Deployment` antigo continua vivo até as execuções dele terminarem. Ver [Como fazer deploy de uma nova versão do workload](/construir/configurar-e-hospedar/como-fazer-deploy-de-uma-nova-versao-do-workload.md).

## Azure

Container Apps: a mesma imagem do passo anterior, com as variáveis em environment variables e `SKAIL_KEY` como secret reference. Mantenha ao menos uma réplica: com zero réplicas ninguém busca trabalho e as execuções ficam esperando.

App Service: as Application settings viram variáveis de ambiente para o processo; use referência ao Key Vault para `SKAIL_KEY`. O App Service foi feito para processos que atendem HTTP; para um Worker Service puro, prefira Container Apps ou hospede o worker como WebJob contínuo.

## Erros comuns

| Sintoma                                               | Causa provável                                                                                                     | Correção                                                      |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `There is not Skail runtime available!`               | Faltou `UseSkail()`, ou o IL weaving não rodou (build sem o pacote), ou falta `[assembly: VisibleToSkailPlatform]` | Confira o `Program.cs` e refaça o build com o pacote presente |
| `StateMachine not registered.`                        | Método decorado não descoberto: sem `async`, assinatura errada, assembly sem o atributo                            | Ver [SkailFunction](/construir/sdk-.net/skailfunction.md)     |
| `Unauthenticated` no log                              | `SKAIL_KEY` ou `SKAIL_NAMESPACE` errados (segredo não montado no container é a causa mais comum)                   | Confira o `Secret` e a referência em `env`                    |
| `Message image mismatch` ou `Target method not found` | `SKAIL_WORKLOAD` do processo diferente do workload endereçado                                                      | Alinhe `nome:versao` com o portal e com o caminho do trigger  |
| `The Builder Factory can only be registered once!`    | `UseSkail()`/`AddSkail()` chamado duas vezes                                                                       | Uma chamada por processo                                      |

## Próximos passos

[Variáveis de ambiente do runtime](/construir/variaveis-de-ambiente-do-runtime.md) é a referência das variáveis. [Como rodar localmente](/construir/configurar-e-hospedar/como-rodar-localmente.md) cobre a máquina do desenvolvedor. [Ambientes e promoção](/operar/readme.md) explica o que muda entre dev, homologação e produção.