Durable Task Roslyn Analyzer for C# orchestrations

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 Severidade Descrição Correção de código
DURABLE0001 Aviso 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. Yes
DURABLE0002 Aviso Detecta Guid.NewGuid() em orquestrações. Use context.NewGuid() em seu lugar. Yes
DURABLE0003 Aviso Detecta Task.Delay ou Thread.Sleep em orquestrações. Use context.CreateTimer em seu lugar. Yes
DURABLE0004 Aviso Detecta APIs de threads e tarefas não determinísticas (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) em orquestrações. No
DURABLE0005 Aviso 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 Aviso Detecta o uso da System.Environment API (por exemplo, GetEnvironmentVariable) em orquestrações. No
DURABLE0007 Aviso Detecta parâmetros CancellationToken em assinaturas de função de orquestração. No
DURABLE0008 Aviso 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 Aviso Detecta o uso não contextual ILogger em orquestrações. Use context.CreateReplaySafeLogger() em seu lugar. No
DURABLE0011 Aviso 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 Severidade Descrição Correção de código
DURABLE0001 Aviso 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. Yes
DURABLE0002 Aviso Detecta Guid.NewGuid() em orquestrações. Use context.NewGuid() em seu lugar. Yes
DURABLE0003 Aviso Detecta Task.Delay ou Thread.Sleep em orquestrações. Use context.CreateTimer em seu lugar. Yes
DURABLE0004 Aviso Detecta APIs de threads e tarefas não determinísticas (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) em orquestrações. No
DURABLE0005 Aviso 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 Aviso 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 Aviso Detecta o uso não contextual ILogger em orquestrações. Use context.CreateReplaySafeLogger() em seu lugar. No
DURABLE0011 Aviso 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

Observação

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 Severidade Descrição Correção de código
DURABLE1001 Erro [OrchestrationTrigger] Garante que só seja aplicado a TaskOrchestrationContext parâmetros. Yes
DURABLE1002 Erro [DurableClient] Garante que só seja aplicado a DurableTaskClient parâmetros. Yes
DURABLE1003 Erro [EntityTrigger] Garante que só seja aplicado a TaskEntityDispatcher parâmetros. Yes

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 Severidade Descrição Correção de código
DURABLE2001 Aviso Detecta incompatibilidades de tipo de entrada entre invocações de atividade e definições de atividade. No
DURABLE2002 Aviso 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 modelo de programação em processo .NET está sendo descontinuado. Use o .NET modelo de trabalho isolado para novos projetos. 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

  • Last updated on