Durable Task Roslyn Analyzer per orchestrazioni C#

Durable Task Roslyn Analyzer è un analizzatore di codice live che consente di seguire i vincoli di codice orchestrator nelle app C# Durable Functions. Rileva problemi comuni, ad esempio l'utilizzo delle API non deterministiche, le associazioni errate e le mancate corrispondenze del tipo in fase di compilazione, prima che il codice raggiunga la produzione.

L'analizzatore è incluso nel pacchetto NuGet Microsoft.Azure.Functions.Worker.Extensions.DurableTask (v1.6.0 e versioni successive) ed è abilitato per impostazione predefinita. Non è necessaria alcuna configurazione aggiuntiva.

Durable Task Roslyn Analyzer è un analizzatore di codice live che consente di seguire i vincoli di codice dell'agente di orchestrazione nelle app C# Durable Task SDK. Rileva problemi comuni, ad esempio l'utilizzo delle API non deterministiche e le mancate corrispondenze del tipo in fase di compilazione, prima che il codice raggiunga la produzione.

Per usare l'analizzatore, aggiungere il Microsoft.DurableTask.Analyzers pacchetto NuGet al progetto:

dotnet add package Microsoft.DurableTask.Analyzers

Come funziona

L'analizzatore viene eseguito automaticamente in Visual Studio, Visual Studio Code (con l'estensione C# Dev Kit) e durante dotnet build nella riga di comando. Esamina il codice dell'orchestratore e riporta la diagnostica come avvisi o errori nell'elenco degli errori dell'IDE e nell'uscita di compilazione.

Non è necessaria alcuna configurazione dell'IDE per analizzare i file aperti. L'analizzatore viene attivato non appena il pacchetto NuGet è presente nel progetto.

Suggerimento

Per impostazione predefinita, Visual Studio esegue solo analizzatori sui file aperti. Per analizzare l'intera soluzione contemporaneamente, passare a Strumenti>Opzioni>Editor> di testoC#>Avanzate e impostare Ambito di analisi in background su Intera soluzione.

Per diverse regole, l'analizzatore fornisce anche correzioni di codice automatiche (azioni rapide) in Visual Studio e VS Code. Ad esempio, può sostituire DateTime.Now con context.CurrentUtcDateTime in un singolo clic.

Regole dell'analizzatore

Le sezioni seguenti elencano le regole dell'analizzatore fornite con Durable Task Roslyn Analyzer, raggruppate per categoria.

Regole di orchestrazione

Queste regole applicano vincoli di codice dell'agente di orchestrazione rilevando l'utilizzo di API non deterministiche o non sicure all'interno di metodi di orchestrazione.

ID Regola Severity Descrizione Correzione del codice
DURABLE0001 Avvertimento Rileva proprietà non deterministiche DateTime (DateTime.Now, DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) nelle orchestrazioni. Utilizzare invece context.CurrentUtcDateTime. Yes
DURABLE0002 Avvertimento Rileva Guid.NewGuid() nelle orchestrazioni. Utilizzare invece context.NewGuid(). Yes
DURABLE0003 Avvertimento Task.Delay Rileva Thread.Sleep nelle orchestrazioni. Utilizzare invece context.CreateTimer. Yes
DURABLE0004 Avvertimento Rileva le API non deterministiche per thread e task (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) nelle orchestrazioni. No
DURABLE0005 Avvertimento Rileva le API di I/O (ad esempio, HttpClient, Archiviazione di Azure client) usate direttamente nelle orchestrazioni. Spostare le chiamate di I/O alle attività. No
DURABLE0006 Avvertimento Rileva l'utilizzo dell'API System.Environment , ad esempio , GetEnvironmentVariablenelle orchestrazioni. No
DURABLE0007 Avvertimento Rileva i CancellationToken parametri nelle firme delle funzioni di orchestrazione. No
DURABLE0008 Avvertimento Rileva associazioni non[OrchestrationTrigger] , ad esempio [EntityTrigger], [DurableClient]nei parametri della funzione di orchestrazione. No
DURABLE0009 Informazioni Suggerisce l'uso di un parametro di input anziché di context.GetInput<T>(). No
DURABLE0010 Avvertimento Rileva l'utilizzo non contestuale ILogger nelle orchestrazioni. Utilizzare invece context.CreateReplaySafeLogger(). No
DURABLE0011 Avvertimento Rileva cicli di orchestrazione non associati while (true) che non chiamano ContinueAsNew. Senza ContinueAsNew, la cronologia dell'orchestrazione cresce per un periodo illimitato. No
ID Regola Severity Descrizione Correzione del codice
DURABLE0001 Avvertimento Rileva proprietà non deterministiche DateTime (DateTime.Now, DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) nelle orchestrazioni. Utilizzare invece context.CurrentUtcDateTime. Yes
DURABLE0002 Avvertimento Rileva Guid.NewGuid() nelle orchestrazioni. Utilizzare invece context.NewGuid(). Yes
DURABLE0003 Avvertimento Task.Delay Rileva Thread.Sleep nelle orchestrazioni. Utilizzare invece context.CreateTimer. Yes
DURABLE0004 Avvertimento Rileva le API non deterministiche per thread e task (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) nelle orchestrazioni. No
DURABLE0005 Avvertimento Rileva le API di I/O (ad esempio, HttpClient, Archiviazione di Azure client) usate direttamente nelle orchestrazioni. Spostare le chiamate di I/O alle attività. No
DURABLE0006 Avvertimento Rileva l'utilizzo dell'API System.Environment , ad esempio , GetEnvironmentVariablenelle orchestrazioni. No
DURABLE0009 Informazioni Suggerisce l'uso di un parametro di input anziché di context.GetInput<T>(). No
DURABLE0010 Avvertimento Rileva l'utilizzo non contestuale ILogger nelle orchestrazioni. Utilizzare invece context.CreateReplaySafeLogger(). No
DURABLE0011 Avvertimento Rileva cicli di orchestrazione non associati while (true) che non chiamano ContinueAsNew. Senza ContinueAsNew, la cronologia dell'orchestrazione cresce per un periodo illimitato. No

Annotazioni

Le regole DURABLE0007, le DURABLE0008 e le DURABLE1001-DURABLE1003 si applicano solo a Funzioni di Azure e non sono incluse nell'analizzatore autonomo di Durable Task SDK.

Regole di associazione

Queste regole convalidano che i binding di trigger e client vengano applicati ai tipi di parametro corretti.

ID Regola Severity Descrizione Correzione del codice
DURABLE1001 Error Assicura che [OrchestrationTrigger] venga applicato solo ai parametri TaskOrchestrationContext. Yes
DURABLE1002 Error Assicura che [DurableClient] venga applicato solo ai parametri DurableTaskClient. Yes
DURABLE1003 Error Assicura che [EntityTrigger] venga applicato solo ai parametri TaskEntityDispatcher. Yes

Regole di attività

Queste regole controllano la mancata corrispondenza dei tipi e i nomi non risolti nelle chiamate di attività e orchestrazione secondaria.

ID Regola Severity Descrizione Correzione del codice
DURABLE2001 Avvertimento Rileva mancate corrispondenze del tipo di input tra le chiamate di attività e le definizioni di attività. No
DURABLE2002 Avvertimento Rileva le mancate corrispondenze del tipo di output tra le chiamate di attività e le definizioni di attività. No
DURABLE2003 Informazioni Segnala quando una chiamata di attività fa riferimento a un nome che non corrisponde ad alcuna attività definita nella compilazione. No
DURABLE2004 Informazioni Segnala quando una chiamata di orchestrazione secondaria fa riferimento a un nome che non corrisponde ad alcun agente di orchestrazione definito nella compilazione. No

Per altre informazioni, vedere le note sulla versione di analyzer su GitHub.

Eliminare gli avvisi dell'analizzatore Roslyn

È possibile eliminare la diagnostica dell'analizzatore a livello di progetto, file o riga.

Sopprimi con .editorconfig

Aggiungere una voce al file .editorconfig per modificare il livello di gravità di una regola o disabilitarla completamente:

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

I valori di gravità validi sono error, warning, suggestion, silente none.

Eliminare l'inline con #pragma

Usare #pragma warning disable per eliminare un avviso specifico in una sezione di codice:

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

Eliminare a livello di progetto

Aggiungere una voce <NoWarn> al file .csproj per eliminare una regola per l'intero progetto:

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

Analizzatore .NET legacy in-process

Esiste un analizzatore Roslyn separato e precedente per il modello di programmazione .NET in-process. Questo analizzatore fa parte del pacchetto Microsoft.Azure.WebJobs.Extensions.DurableTask e usa un prefisso di regola diverso (DF anziché DURABLE). I due analizzatori sono pacchetti completamente separati e non condividono ID regola.

Importante

Il .NET modello di programmazione in-process viene ritirato. Usare il modello del processo di lavoro .NET isolato per nuovi progetti. L'analizzatore in-process legacy non riceve nuove regole o miglioramenti.

Per informazioni sulle regole dell'analizzatore in-process (DF0101-DF0307), vedere la pagina della versione Analyzer v0.2.0.

Passo successivo

Vincoli di codice della funzione di Orchestrator

  • Last updated on