Durable Task Roslyn Analyzer för C#-orkestreringar

Durable Task Roslyn Analyzer är en live-kodanalysator som hjälper dig att följa orchestrator code constraints i dina C# Durable Functions-applikationer. Den identifierar vanliga problem som icke-deterministisk API-användning, felaktiga bindningar och typmatchningar vid byggtid, innan koden når produktion.

Analysatorn paketeras med Microsoft.Azure.Functions.Worker.Extensions.DurableTask NuGet-paketet (v1.6.0 och senare) och är aktiverat som standard. Ingen extra installation krävs.

Durable Task Roslyn Analyzer är en live-kodanalysator som hjälper dig att följa orchestrator-kodbegränsningar i dina C# Durable Task SDK-appar. Den identifierar vanliga problem som icke-deterministisk API-användning och typmatchningar vid byggtid, innan koden når produktion.

Om du vill använda analysatorn lägger du till Microsoft.DurableTask.Analyzers NuGet-paketet i projektet:

dotnet add package Microsoft.DurableTask.Analyzers

Så här fungerar det

Analysatorn körs automatiskt i Visual Studio, Visual Studio Code (med tillägget C# Dev Kit) och under dotnet build på kommandoraden. Den inspekterar orkestreringskoden och rapporterar diagnostik som varningar eller fel i IDE:ns fellista och i byggutdata.

Ingen IDE-konfiguration krävs för att analysera öppna filer. Analysatorn aktiveras så snart NuGet-paketet finns i projektet.

Tips/Råd

Som standard kör Visual Studio bara analysverktyg på filer som du har öppna. Om du vill analysera hela lösningen på en gång går du till Verktygsalternativ>>Textredigeraren>C#>Avancerat och anger Omfång för bakgrundsanalys till Hela lösningen.

För flera regler tillhandahåller analysatorn även automatiska kodkorrigeringar (snabbåtgärder) i Visual Studio och VS Code. Den kan till exempel ersättas DateTime.Now med context.CurrentUtcDateTime med ett enda klick.

Analysatorregler

I följande avsnitt visas de analysregler som levereras med Durable Task Roslyn Analyzer, grupperade efter kategori.

Orkestreringsregler

Dessa regler tillämpar orchestrator-kodbegränsningar genom att identifiera icke-deterministisk eller osäker API-användning i orkestreringsmetoder.

Regel-ID Severity Beskrivning Kodkorrigering
DURABLE0001 Varning Identifierar icke-deterministiska DateTime egenskaper (DateTime.Now, DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) i orkestreringar. Använd context.CurrentUtcDateTime i stället. Yes
DURABLE0002 Varning Identifierar Guid.NewGuid() i orkestreringar. Använd context.NewGuid() i stället. Yes
DURABLE0003 Varning Upptäcker Task.Delay och Thread.Sleep i orkestrering. Använd context.CreateTimer i stället. Yes
DURABLE0004 Varning Identifierar icke-deterministiska tråd- och aktivitets-API:er (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) i orkestreringar. No
DURABLE0005 Varning Identifierar I/O-API:er (till exempel HttpClient, Azure Storage klienter) som används direkt i orkestreringar. Flytta I/O-anrop till aktiviteter. No
DURABLE0006 Varning Identifierar System.Environment API-användning (till exempel GetEnvironmentVariable) i orkestreringar. No
DURABLE0007 Varning Identifierar parametrar i orkestreringsfunktionens CancellationToken signaturer. No
DURABLE0008 Varning Identifierar icke-bindningar[OrchestrationTrigger] (till exempel [EntityTrigger], [DurableClient]) i orkestreringsfunktionsparametrar. No
DURABLE0009 Info Föreslår att du använder en indataparameter istället för context.GetInput<T>(). No
DURABLE0010 Varning Identifierar icke-kontextuell ILogger användning i orkestreringar. Använd context.CreateReplaySafeLogger() i stället. No
DURABLE0011 Varning Identifierar obundna while (true) orkestreringsloopar som inte anropar ContinueAsNew. Utan ContinueAsNewväxer orkestreringshistoriken på obestämd tid. No
Regel-ID Severity Beskrivning Kodkorrigering
DURABLE0001 Varning Identifierar icke-deterministiska DateTime egenskaper (DateTime.Now, DateTime.UtcNow, DateTime.Today, DateTimeOffset.Now, DateTimeOffset.UtcNow) i orkestreringar. Använd context.CurrentUtcDateTime i stället. Yes
DURABLE0002 Varning Identifierar Guid.NewGuid() i orkestreringar. Använd context.NewGuid() i stället. Yes
DURABLE0003 Varning Upptäcker Task.Delay och Thread.Sleep i orkestrering. Använd context.CreateTimer i stället. Yes
DURABLE0004 Varning Identifierar icke-deterministiska tråd- och aktivitets-API:er (Thread.Start, Task.Run, Task.ContinueWith, TaskFactory.StartNew) i orkestreringar. No
DURABLE0005 Varning Identifierar I/O-API:er (till exempel HttpClient, Azure Storage klienter) som används direkt i orkestreringar. Flytta I/O-anrop till aktiviteter. No
DURABLE0006 Varning Identifierar System.Environment API-användning (till exempel GetEnvironmentVariable) i orkestreringar. No
DURABLE0009 Info Föreslår att du använder en indataparameter istället för context.GetInput<T>(). No
DURABLE0010 Varning Identifierar icke-kontextuell ILogger användning i orkestreringar. Använd context.CreateReplaySafeLogger() i stället. No
DURABLE0011 Varning Identifierar obundna while (true) orkestreringsloopar som inte anropar ContinueAsNew. Utan ContinueAsNewväxer orkestreringshistoriken på obestämd tid. No

Anmärkning

Regler DURABLE0007, DURABLE0008 och DURABLE1001-DURABLE1003 gäller endast för Azure Functions och ingår inte i den fristående Durable Task SDK-analysatorn.

Bindningsregler

Dessa regler verifierar att utlösare och klientbindningar tillämpas på rätt parametertyper.

Regel-ID Severity Beskrivning Kodkorrigering
DURABLE1001 Error Säkerställer att [OrchestrationTrigger] endast tillämpas på TaskOrchestrationContext parametrar. Yes
DURABLE1002 Error Säkerställer att [DurableClient] endast tillämpas på DurableTaskClient parametrar. Yes
DURABLE1003 Error Säkerställer att [EntityTrigger] endast tillämpas på TaskEntityDispatcher parametrar. Yes

Aktivitetsregler

Dessa regler söker efter typmatchningar och olösta namn i aktivitets- och underorkestreringsanrop.

Regel-ID Severity Beskrivning Kodkorrigering
DURABLE2001 Varning Identifierar indatatypsmatchningar mellan aktivitetsanrop och aktivitetsdefinitioner. No
DURABLE2002 Varning Identifierar matchningsfel för utdatatyp mellan aktivitetsanrop och aktivitetsdefinitioner. No
DURABLE2003 Info Rapporterar när ett aktivitetsanrop refererar till ett namn som inte matchar någon definierad aktivitet i kompileringen. No
DURABLE2004 Info Rapporter när ett underorkestreringsanrop refererar till ett namn som inte matchar någon definierad orkestrerare i kompileringen. No

För mer information, se analyzer versionsanteckningar på GitHub.

Ignorera Roslyn Analyzer-varningar

Du kan förhindra analysdiagnostik på projekt-, fil- eller linjenivå.

Undertryck med .editorconfig

Lägg till en post i .editorconfig filen för att ändra allvarlighetsgraden för en regel eller inaktivera den helt:

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

Giltiga allvarlighetsvärden är error, warning, suggestion, silentoch none.

Dölj direkt med #pragma

Använd #pragma warning disable för att utelämna en specifik varning i ett kodavsnitt:

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

Ignorera på projektnivå

Lägg till en <NoWarn> post i .csproj filen för att utelämna en regel för hela projektet:

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

Äldre .NET-analysverktyg i processen

Det finns en separat, äldre Roslyn-analysator för programmeringsmodellen .NET in-process. Den här analysatorn är en del av paketet Microsoft.Azure.WebJobs.Extensions.DurableTask och använder ett annat regelprefix (DF i stället för DURABLE). De två analysverktygen är helt separata paket och delar inte regel-ID:t.

Viktigt!

Den .NET in-process-programmeringsmodellen fasas ut. Använd .NET isolerad arbetsmodell för nya projekt. Den äldre processanalysatorn tar inte emot nya regler eller förbättringar.

Information om de processbaserade analysreglerna (DF0101–DF0307) finns på versionssidan Analyzer v0.2.0.

Nästa steg