Analisador Roslyn de Tarefas Duráveis para orquestrações em C#

O Durable Task Roslyn Analyzer é um analisador de código em tempo real que ajuda você a seguir as restrições de código do orquestrador em seus aplicativos C# de Durable Functions. Ele detecta problemas comuns, como uso de API não determinística, associações incorretas e incompatibilidades de tipo no tempo de build, antes que seu código atinja a produção.

O analisador é agrupado com o pacote NuGet Microsoft.Azure.Functions.Worker.Extensions.DurableTask (v1.6.0 e posterior) e está habilitado por padrão. Nenhuma configuração extra é necessária.

O Analisador Roslyn de Tarefas Duráveis é um analisador de código em tempo real que ajuda a seguir restrições de código do orquestrador nos seus aplicativos C# do SDK da Tarefa Durável. Ele detecta problemas comuns, como uso de API não determinística e incompatibilidades de tipo no tempo de build, antes que seu código atinja a produção.

Para usar o analisador, adicione o Microsoft.DurableTask.Analyzers pacote NuGet ao seu projeto:

dotnet add package Microsoft.DurableTask.Analyzers

Como funciona

O analisador é executado automaticamente em Visual Studio, Visual Studio Code (com a extensão C# Dev Kit) e durante dotnet build na linha de comando. Ele inspeciona o código do orquestrador e relata o diagnóstico como avisos ou erros na lista de erros do IDE e na saída do build.

Nenhuma configuração de IDE é necessária para analisar arquivos abertos. O analisador é ativado assim que o pacote NuGet está presente em seu projeto.

Dica

Por padrão, Visual Studio só executa analisadores em arquivos abertos. Para analisar toda a solução de uma só vez, vá parao Editor> de Texto deOpções>de Ferramentas>C#>Avançado e defina o escopo de análise em segundo plano como solução Inteira.

Para várias regras, o analisador também fornece correções de código automáticas (ações rápidas) em Visual Studio e VS Code. Por exemplo, ele pode substituir DateTime.Now em context.CurrentUtcDateTime um único clique.

Regras do analisador

As seções a seguir listam as regras do analisador que são enviadas com o Analisador Roslyn de Tarefa Durável, agrupados por categoria.

Regras de orquestração

Essas regras impõem restrições de código do orquestrador detectando o uso de API não determinística ou não segura dentro de métodos de orquestração.

ID da regra	Severity	Description	Correção de código
DURABLE0001	Warning	Detecta propriedades não determinísticas DateTime (DateTime.Now, , DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) em orquestrações. Use context.CurrentUtcDateTime em seu lugar.	Sim
DURABLE0002	Warning	Detecta Guid.NewGuid() em orquestrações. Use context.NewGuid() em seu lugar.	Sim
DURABLE0003	Warning	Detecta Task.Delay ou Thread.Sleep em orquestrações. Use context.CreateTimer em seu lugar.	Sim
DURABLE0004	Warning	Detecta APIs de threads e tarefas não determinísticas (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) em orquestrações.	No
DURABLE0005	Warning	Detecta APIs de E/S (por exemplo, clientes do Armazenamento do Azure) que são usadas diretamente em orquestrações. Mover chamadas de E/S para atividades.	No
DURABLE0006	Warning	Detecta o uso da System.Environment API (por exemplo, GetEnvironmentVariable) em orquestrações.	No
DURABLE0007	Warning	Detecta parâmetros CancellationToken em assinaturas de função de orquestração.	No
DURABLE0008	Warning	Detecta associações não[OrchestrationTrigger] (por exemplo, [EntityTrigger], [DurableClient]) nos parâmetros de função de orquestração.	No
DURABLE0009	Informações	Sugere o uso de um parâmetro de entrada em vez de context.GetInput<T>().	No
DURABLE0010	Warning	Detecta o uso não contextual ILogger em orquestrações. Use context.CreateReplaySafeLogger() em seu lugar.	No
DURABLE0011	Warning	Detecta loops de orquestração não associados while (true) que não chamam ContinueAsNew. Sem ContinueAsNew, a história da orquestração cresce indefinidamente.	No

ID da regra	Severity	Description	Correção de código
DURABLE0001	Warning	Detecta propriedades não determinísticas DateTime (DateTime.Now, , DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) em orquestrações. Use context.CurrentUtcDateTime em seu lugar.	Sim
DURABLE0002	Warning	Detecta Guid.NewGuid() em orquestrações. Use context.NewGuid() em seu lugar.	Sim
DURABLE0003	Warning	Detecta Task.Delay ou Thread.Sleep em orquestrações. Use context.CreateTimer em seu lugar.	Sim
DURABLE0004	Warning	Detecta APIs de threads e tarefas não determinísticas (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) em orquestrações.	No
DURABLE0005	Warning	Detecta APIs de E/S (por exemplo, clientes do Armazenamento do Azure) que são usadas diretamente em orquestrações. Mover chamadas de E/S para atividades.	No
DURABLE0006	Warning	Detecta o uso da System.Environment API (por exemplo, GetEnvironmentVariable) em orquestrações.	No
DURABLE0009	Informações	Sugere o uso de um parâmetro de entrada em vez de context.GetInput<T>().	No
DURABLE0010	Warning	Detecta o uso não contextual ILogger em orquestrações. Use context.CreateReplaySafeLogger() em seu lugar.	No
DURABLE0011	Warning	Detecta loops de orquestração não associados while (true) que não chamam ContinueAsNew. Sem ContinueAsNew, a história da orquestração cresce indefinidamente.	No

Note

As regras DURABLE0007, DURABLE0008 e DURABLE1001-DURABLE1003 se aplicam apenas a Azure Functions e não estão incluídas no analisador autônomo do SDK de Tarefas Duráveis.

Regras de associação

Essas regras validam que as associações de gatilho e cliente são aplicadas aos tipos de parâmetro corretos.

ID da regra	Severity	Description	Correção de código
DURABLE1001	Erro	[OrchestrationTrigger] Garante que só seja aplicado a TaskOrchestrationContext parâmetros.	Sim
DURABLE1002	Erro	[DurableClient] Garante que só seja aplicado a DurableTaskClient parâmetros.	Sim
DURABLE1003	Erro	[EntityTrigger] Garante que só seja aplicado a TaskEntityDispatcher parâmetros.	Sim

Regras de atividade

Essas regras verificam se há incompatibilidades de tipo e nomes não resolvidos em chamadas de atividade e sub-orquestração.

ID da regra	Severity	Description	Correção de código
DURABLE2001	Warning	Detecta incompatibilidades de tipo de entrada entre invocações de atividade e definições de atividade.	No
DURABLE2002	Warning	Detecta incompatibilidades de tipo de saída entre invocações de atividade e definições de atividade.	No
DURABLE2003	Informações	Relata quando uma chamada de atividade faz referência a um nome que não corresponde a nenhuma atividade definida na compilação.	No
DURABLE2004	Informações	Relata quando uma chamada de suborquestração faz referência a um nome que não corresponde a nenhum orquestrador definido na compilação.	No

Para obter mais informações, consulte as notas de versão analyzer no GitHub.

Suprimir avisos do Analisador Roslyn

Você pode suprimir o diagnóstico do analisador no nível de projeto, arquivo ou linha.

Suprimir com .editorconfig

Adicione uma entrada ao arquivo .editorconfig para alterar a gravidade de uma regra ou desabilitá-la inteiramente:

[*.cs]
dotnet_diagnostic.DURABLE0001.severity = none

Os valores de severidade válidos sãoerror, warning, , suggestione silentnone.

Suprimir embutido com #pragma

Use #pragma warning disable para suprimir um aviso específico em uma seção do código:

#pragma warning disable DURABLE0001
var now = DateTime.UtcNow;
#pragma warning restore DURABLE0001

Suprimir no nível do projeto

Adicione uma <NoWarn> entrada ao arquivo .csproj para suprimir uma regra para todo o projeto:

<PropertyGroup>
  <NoWarn>$(NoWarn);DURABLE0001</NoWarn>
</PropertyGroup>

Analisador .NET em processo herdado

Existe um analisador Roslyn separado e antigo para o modelo de programação .NET em processo. Esse analisador faz parte do pacote Microsoft.Azure.WebJobs.Extensions.DurableTask e usa um prefixo de regra diferente (DF em vez de DURABLE). Os dois analisadores são pacotes totalmente separados e não compartilham IDs de regra.

Importante

O suporte terminará para o modelo em andamento em 10 de novembro de 2026. É altamente recomendável migrar seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

O analisador em processo legado não recebe novas regras ou melhorias.

Para obter informações sobre as regras do analisador em processo (DF0101–DF0307), consulte a página de versão Analyzer v0.2.0.

Próxima etapa

Restrições de código de função do Orchestrator