Durable Task Roslyn Analyzer para orquestrações em C#

O Durable Task Roslyn Analyzer é um analisador de código ao vivo que o ajuda a seguir as restrições do código orchestrator nas suas aplicações de Durable Functions C#. Deteta problemas comuns como uso não determinístico da API, bindings incorretos e incompatibilidades de tipos durante a compilação, antes do seu código chegar à produção.

O analisador está incluído no pacote NuGet Microsoft.Azure.Functions.Worker.Extensions.DurableTask (v1.6.0 e posteriores) e está ativado por padrão. Não é necessária qualquer configuração extra.

O Durable Task Roslyn Analyzer é um analisador de código ao vivo que o ajuda a seguir as restrições do código do orquestrador nas suas aplicações SDK de Tarefas Duráveis em C#. Deteta problemas comuns como uso não determinístico da API e incompatibilidades de tipos durante a compilação, antes do seu código chegar à 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 corre automaticamente em Visual Studio, Visual Studio Code (com a extensão C# Dev Kit) e durante dotnet build na linha de comandos. Inspeciona o código do teu orquestrador e reporta diagnósticos como avisos ou erros na lista de erros do teu IDE e na saída da compilação.

Não é necessária qualquer configuração do IDE para analisar ficheiros abertos. O analisador ativa assim que o pacote NuGet está presente no seu projeto.

Sugestão

Por defeito, o Visual Studio só executa analisadores nos ficheiros que tem abertos. Para analisar toda a sua solução de uma só vez, vá a Ferramentas>Opções>Editor de Texto>C#>Advanced e defina o âmbito de análise em segundo plano para Solução completa.

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

Regras do analisador

As secções seguintes listam as regras do analisador que acompanham o Analisador Roslyn de Tarefas Duradouras, agrupadas por categoria.

Regras de orquestração

Estas regras impõem restrições ao código do orquestrador ao detetar o uso de APIs não determinístico ou inseguro dentro dos métodos de orquestração.

ID da regra Severity Descrição Correção de código
DURABLE0001 Advertência Deteta propriedades não determinísticas DateTime (DateTime.Now, DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) em orquestrações. Utilize context.CurrentUtcDateTime em substituição. Yes
DURABLE0002 Advertência Deteta Guid.NewGuid() em orquestrações. Utilize context.NewGuid() em substituição. Yes
DURABLE0003 Advertência Deteta Task.Delay ou Thread.Sleep em orquestrações. Utilize context.CreateTimer em substituição. Yes
DURABLE0004 Advertência Deteta APIs de threads e tarefas não determinísticas (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) em orquestrações. No
DURABLE0005 Advertência Deteta APIs de I/O (por exemplo, HttpClient, clientes de Armazenamento do Azure) utilizadas diretamente nas orquestrações. Transferir chamadas de I/O para atividades. No
DURABLE0006 Advertência Deteta a utilização de System.Environment API (por exemplo, GetEnvironmentVariable) em orquestrações. No
DURABLE0007 Advertência Deteta CancellationToken parâmetros em assinaturas de funções de orquestração. No
DURABLE0008 Advertência Deteta ligações não-[OrchestrationTrigger] (por exemplo, [EntityTrigger], [DurableClient]) em parâmetros da função de orquestração. No
DURABLE0009 Informações Sugere usar um parâmetro de entrada em vez de context.GetInput<T>(). No
DURABLE0010 Advertência Deteta o uso não contextual ILogger em orquestrações. Utilize context.CreateReplaySafeLogger() em substituição. No
DURABLE0011 Advertência Deteta loops de orquestração ilimitados while (true) que não chamam ContinueAsNew. Sem ContinueAsNew, a história da orquestração cresce indefinidamente. No
ID da regra Severity Descrição Correção de código
DURABLE0001 Advertência Deteta propriedades não determinísticas DateTime (DateTime.Now, DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) em orquestrações. Utilize context.CurrentUtcDateTime em substituição. Yes
DURABLE0002 Advertência Deteta Guid.NewGuid() em orquestrações. Utilize context.NewGuid() em substituição. Yes
DURABLE0003 Advertência Deteta Task.Delay ou Thread.Sleep em orquestrações. Utilize context.CreateTimer em substituição. Yes
DURABLE0004 Advertência Deteta APIs de threads e tarefas não determinísticas (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) em orquestrações. No
DURABLE0005 Advertência Deteta APIs de I/O (por exemplo, HttpClient, clientes de Armazenamento do Azure) utilizadas diretamente nas orquestrações. Transferir chamadas de I/O para atividades. No
DURABLE0006 Advertência Deteta a utilização de System.Environment API (por exemplo, GetEnvironmentVariable) em orquestrações. No
DURABLE0009 Informações Sugere usar um parâmetro de entrada em vez de context.GetInput<T>(). No
DURABLE0010 Advertência Deteta o uso não contextual ILogger em orquestrações. Utilize context.CreateReplaySafeLogger() em substituição. No
DURABLE0011 Advertência Deteta loops de orquestração ilimitados 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 aplicam-se apenas a Funções do Azure e não estão incluídas no analisador independente do Durable Task SDK.

Regras vinculativas

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

ID da regra Severity Descrição Correção de código
DURABLE1001 Erro Assegura que [OrchestrationTrigger] é aplicado apenas a parâmetros TaskOrchestrationContext. Yes
DURABLE1002 Erro Assegura que [DurableClient] é aplicado apenas a parâmetros DurableTaskClient. Yes
DURABLE1003 Erro Assegura que [EntityTrigger] é aplicado apenas a parâmetros TaskEntityDispatcher. Yes

Regras da atividade

Estas regras verificam incompatibilidades de tipo e nomes não resolvidos em chamadas de atividade e suborquestração.

ID da regra Severity Descrição Correção de código
DURABLE2001 Advertência Detetar incompatibilidades no tipo de entrada entre invocações de atividade e definições de atividade. No
DURABLE2002 Advertência Deteta incompatibilidades de tipos de saída entre invocações de atividade e definições de atividade. No
DURABLE2003 Informações Reporta 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 sub-orquestração referencia um nome que não corresponde a nenhum orquestrador definido na compilação. No

Para mais informações, consulte as notas de lançamento analyzer no GitHub.

Suprimir avisos do Roslyn Analyzer

Pode suprimir diagnósticos do analisador ao nível do projeto, ficheiro ou linha.

Suprimir com .editorconfig

Adicione uma entrada ao seu .editorconfig ficheiro para alterar a gravidade de uma regra ou desative-a completamente:

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

Os valores válidos de severidade são error, warning, suggestion, silent, e none.

Suprimir em linha com #pragma

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

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

Suprimir ao nível do projeto

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

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

Analisador .NET em processo antigo

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

Importante

O modelo de programação em processo .NET está a ser retirado. Use o modelo .NET trabalhador isolado para novos projetos. O analisador legado em execução não recebe novas regras nem melhorias.

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

Próximo passo

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

  • Last updated on