Erstellen von Workflow-Analyseregeln

Die Workflow-Analyse ist ein Tool, mit dem Sie sicherstellen können, dass Ihr Projekt den Anforderungen an Best Practices, Wartbarkeit, Lesbarkeit, Leistung, Wiederverwendbarkeit, Zuverlässigkeit und Sicherheit entspricht.

Diese Konzepte sind wichtig für die Gewährleistung sauberer und zuverlässiger Workflows, die große Automatisierungsprojekte zusammenfassen können.

Hinweis: Zum Erstellen benutzerdefinierter Regeln benötigen Sie das API-Paket „UiPath Activities“ aus dem Feed „ Official “. Das SDK-Paket muss als Entwicklungsabhängigkeit in Ihrem benutzerdefinierten Projekt verwendet werden. Lesen Sie mehr über Entwicklungsabhängigkeiten.

Im folgenden Video finden Sie eine Schritt-für-Schritt-Anleitung zum Erstellen benutzerdefinierter Regeln und zum Erstellen benutzerdefinierter Aktivitäten mit der Erweiterung „The Activity Creator “.

In ihrer Standardform ist die Workflow-Analyse in Studio integriert und umfasst Validierungs- und Analysefunktionen. Die Analyse kann nicht durchgeführt werden, wenn die Validierung Fehler zurückgibt.

Konzepte der Workflow-Analyse

Für die Erstellung benutzerdefinierter Regeln für Ihr Projekt sollten eine Reihe von Konzepten definiert werden, um besser zu verstehen, wie die Workflow-Analyse hinter den Kulissen funktioniert.

Hinweis:

When building custom rules, target the .NET version depending on the version of Studio and the project compatibility:

• Studio 2021.4 und früher: .NET Framework 4.6.1.
• Studio 2021.10.6 and later: .NET Framework 4.6.1 for Windows-legacy projects, .NET 6 for Windows and cross-platform projects.

Regeln und Zähler

Die Workflow-Analyse nutzt bestimmte Kriterien, um die Zuverlässigkeit des Projekts zu gewährleisten. Diese Prüfungen werden mit sorgfältig definierten Regeln und Zählern durchgeführt.

Eine Regel stellt eine Anforderung dar, die erfüllt werden muss. Sie kann für Überprüfung des Prüfobjekts anhand der Regeldefinition konfiguriert werden.

Ein Zähler stellt eine Überprüfung dar, die durchgeführt wird, um die Anzahl der Male zu ermitteln, die ein bestimmtes Ereignis oder eine bestimmte Bedingung aufgetreten ist.

Für jede nicht erfüllte Regel wird im Panel „Fehlerliste“ eine Meldung vom Typ „Warnung“, „Fehler“, „Info“ oder „Ausführlich“ angezeigt. Diese Auflistungen enthalten auch Empfehlungen für Änderungen und die Sicherstellung der Einhaltung von Regeln.

Note: When creating custom rules and counters, we recommend following the naming convention detailed in the About Workflow Analyzer page.

Prüfobjekt

Die Workflow-Analyse ist in der Lage, eine eingehende Analyse eines vordefinierten Objekts durchzuführen. Das Objekt stellt den zu analysierenden Scope dar, den Bereich, in dem die Regel oder der Zähler durchgesetzt wird.

• Aktivität: Dies ist das kleinste Prüfobjekt. Namenskonvention für Variablen, Variablenlänge überschritten und Statistik der Dateiaktivitäten sind beispielsweise drei vordefinierte Regeln, die zur Untersuchung von Aktivitäten festgelegt werden können.
• Workflow: Regeln oder Zähler können so festgelegt werden, dass Prüfungen in nur einer Projektdatei durchgeführt werden. Hohe Anzahl von Argumenten und Leere Sequence sind nur zwei vordefinierte Regeln, die den Workflow als Scope haben.
• Projekt: Überprüfungen werden auf Projektebene durchgeführt, um die Zuverlässigkeit des Projekts zu gewährleisten. Nicht verwendete Abhängigkeiten ist eine Regel, die am Projekt-Scope angewendet wird.

Erstellen von Regeln

From the Official feed (https://pkgs.dev.azure.com/uipath/Public.Feeds/_packaging/UiPath-Official/nuget/v3/index.json), install the UiPath.Activities.Api package.

Als Hilfe für die Erstellung einer benutzerdefinierten Regel sehen wir uns eine aktuelle vordefinierte Regel in der Workflow-Analyse an, Variablenlänge überschritten. Diese Regel prüft, ob die Länge der im Projekt definierten Variablen unter 20 Zeichen liegt. Das Prüfobjekt der Regel ist die Aktivität.

Hinter den Kulissen sieht die Regel so aus:

// This static class is not mandatory. It just helps organizining the code.
internal static class VariableLengthRule
    {
  // This should be as unique as possible, and should follow the naming convention.
        private const string RuleId = "ST-NMG-008";
        internal static Rule<IActivityModel> Get()
        {
            var rule = new Rule<IActivityModel>("Variable Length Rule", RuleId, Inspect)
            {
                RecommendationMessage = Recommendation,
              /// Off and Verbose are not supported.
                ErrorLevel = System.Diagnostics.TraceLevel.Warning
            };
            return rule;
        }
  
              // This is the function that executes for each activity in all the files. Might impact performance.
        // The rule instance is the rule provided above which also contains the user-configured data.
                  private static InspectionResult Inspect(IActivityModel activityModel, Rule ruleInstance)
        {
            var messageList = new List<string>();
            foreach(var activityModelVariable in activityModel.Variables)
            {
                if (activityModelVariable.DisplayName.Length > 20)
                {
                    messageList.Add($"The variable {activityModelVariable.DisplayName} has a length longer than 20");
                }
            }
            if (messageList.Count > 0)
            {
                return new InspectionResult()
                {
                    ErrorLevel = ruleInstance.ErrorLevel,
                    HasErrors = true,
                    RecommendationMessage = ruleInstance.RecommendationMessage,
                  // When inspecting a model, a rule can generate more than one message.
                    Messages = messageList
                };
            }
            else
            {
                return new InspectionResult() { HasErrors = false };
            }
        }
    }

Der RuleId-Parameter erfordert den Namen Ihrer Regel. In diesem Beispiel hat die Regel Variablenlänge überschritten die Regel-ID ST-NMG-008 und folge der Namenskonvention für Regeln. Bitte beachten Sie, dass die Namenskonvention, die von den standardmäßig in Studio verfügbaren Regeln verwendet wird, nicht obligatorisch ist.

Der Parameter RecommendationMessage erfordert die Anzeige einer Meldung als Empfehlung, die dem Benutzer nach der Analyse bei der Lösung der gefundenen Inkonsistenzen hilft. Die Meldung sollte prägnant sein und eindeutige Schritte enthalten.

Der Parameter ErrorLevel gibt die Standardaktion für den Fall an, dass die Bedingung nicht erfüllt ist. In diesem Beispiel gibt die Regel eine Warnung aus. Standardaktionen können „Fehler“, „Warnung“, „Info“ oder „Ausführlich“ sein.

Erstellen von Regeln mit Parametern

Die Situation ändert sich geringfügig, wenn wir Regeln erstellen möchten, die anpassbare Parameter enthalten. Eine solcher Regeln ist die Namenskonvention für Variablen. Ihr Prüfelement ist Aktivität, und sie hat einen standardmäßigen regulären Ausdruck, der geändert werden kann.

Hinter den Kulissen sieht diese Regel so aus:

internal static class VariableNamingRule
    {
        private const string RuleId = "ST-NMG-001";
        private const string RegexKey = "Regex";
        private const string DefaultRegex = @"^([A-Z]|[a-z])+([0-9])*$";
        internal static Rule<IActivityModel> Get()
        {
            var rule = new Rule<IActivityModel>(Strings.ST_NMG_001_Name, RuleId, Inspect)
            {
                RecommendationMessage = Recommendation,
                ErrorLevel = System.Diagnostics.TraceLevel.Warning
            };
            rule.Parameters.Add(RegexKey, new Parameter()
        }
                                
       private static InspectionResult Inspect(IActivityModel activityModel, Rule ruleInstance) 
        {
          // This retrieves the parameter value from the rule instance as configured by the user, if not, the default value.
            var setRegexValue = ruleInstance.Parameters[RegexKey]?.Value;
          
            var regex = new Regex(setRegexValue);
            var messageList = new List<string>();
            foreach (var activityModelVariable in activityModel.Variables)
            {
                if(!regex.IsMatch(activityModelVariable.DisplayName))
                {
                    messageList.Add(string.Format(Strings.ST_NMG_001_ErrorFormat, activityModelVariable.DisplayName, setRegexValue));
                }
            }
            if(messageList.Count > 0)
            {
                return new InspectionResult()
                {
                    ErrorLevel = ruleInstance.ErrorLevel,
                    HasErrors = true,
                    RecommendationMessage = ruleInstance.RecommendationMessage,
                    Messages = messageList
                };
            }
            else
            {
                return new InspectionResult() { HasErrors = false };
            }
        }
    }

Beachten Sie, dass sie RuleId, RegexKey und DefaultRegex aufruft, was der standardmäßige reguläre Ausdruck ist, der dieser Regel zugeordnet ist.

Die Parameter RecommendationMessage und ErrorLevel sind die gleichen wie bei der zuvor vorgestellten Regel.

Erstellen von Zählern

Zähler stellen Überprüfungen dar, die durchgeführt werden, um die Anzahl der Male zu ermitteln, die ein bestimmtes Ereignis oder eine bestimmte Bedingung aufgetreten ist.

Ihre Struktur ist insofern etwas anders als die von Regeln, als der einzige verfügbare ErrorLevel-Parameter für Zähler Info ist. Daher sollte der Ausdruck zur Definition der Fehlerstufe für einen Zähler wie folgt aussehen: ErrorLevel = System.Diagnostics.TraceLevel.Info.

Nehmen wir die File Activities Stats als Beispiel dafür, wie Zählerregeln hinter den Kulissen aussehen:

internal static class NumberOfActivitiesInFile
    {
        private const string RuleId = "ST-ANA-009";
        internal static Counter<IActivityModel> Get()
        {
            return new Counter<IActivityModel>(Strings.ST_ANA_009_Name, RuleId, Inspect);
        }
  
  // A Counter<T> receives the entire collection of T objects in the parent structure. e.g. activities in workflow, workflows in project.
  private static InspectionResult Inspect(IReadOnlyCollection<IActivityModel> activities, Counter ruleInstance)
        {
            return new InspectionResult()
            {
              // For a counter, the error level is always info, even if not set here.
                ErrorLevel = System.Diagnostics.TraceLevel.Info,
              // For a counter, the Has Errors field is always ignored.
                HasErrors = false,
                Messages = new List<string>() { string.Format(Strings.ST_ANA_009_ErrorFormat,  activities.Count) }
            };
        }

Buildregeln für StudioX

Standardmäßig gelten Regeln nur für das Studio-Profil. Um eine Regel auch im StudioX-Profil anzeigen zu lassen, fügen Sie die ApplicableScopes-Eigenschaft hinzu, und konfigurieren Sie sie so, dass sie BusinessRule enthält. Sie können die Eigenschaft z. B. wie folgt hinzufügen:

var rule = new Rule<IActivityModel>(Strings.ORG_USG_001_Name, RuleId, Inspect)
            {
                RecommendationMessage = Strings.ORG_USG_001_Recommendation,
                ErrorLevel = TraceLevel.Error,
                //Must contain "BusinessRule" to appear in StudioX, rules always appear in Studio
                ApplicableScopes = new List<string> { RuleConstants.BusinessRule }
            };

Registrierung von Regeln

Methode der Registrierungsschnittstelle

Bitte beachten Sie, dass Ihr Paket auf diese Weise nur mit Studio-Versionen ab 2019.10 kompatibel ist.

Implementieren Sie die IRegisterAnalyzerConfiguration-Schnittstelle mit der folgenden Methode: Initialize(IAnalyzerConfigurationService workflowAnalyzerConfigService).

using UiPath.Studio.Activities.Api;
using UiPath.Studio.Activities.Api.Analyzer;
using UiPath.Studio.RulesLibrary.Rules.Naming;
namespace UiPath.Studio.RulesLibrary
{
    public class RegisterAnalyzerConfiguration : IRegisterAnalyzerConfiguration
    {
        public void Initialize(IAnalyzerConfigurationService workflowAnalyzerConfigService)
        {
            // Naming
            workflowAnalyzerConfigService.AddRule(VariableNamingRule.Get());
            workflowAnalyzerConfigService.AddRule(DisplayNameDuplicationRule.Get());
            workflowAnalyzerConfigService.AddRule(VariableNameDuplicationRule.Get());
            workflowAnalyzerConfigService.AddRule(ArgumentNamingRule.Get());
            workflowAnalyzerConfigService.AddRule(VariableLengthRule.Get());
        }
    }
}

Hinweis: Rufen Sie die Methode HasFeature des IAnalyzerConfigurationService auf, um Regeln für eine bestimmte Studio-Version zu registrieren.

IRegisterMetadata-Methode

Bitte beachten Sie, dass diese Methode nur für Studio-Versionen ab 2019.6 zur Verfügung steht und nicht so geeignet ist wie die Methode der Registrierungsschnittstelle.

• Fügen Sie Ihrer Implementierung von IRegisterMetadata eine Methode vom Typ void Initialize(object api) hinzu.
• In Ihrer Initialize-Implementierung übergeben Sie den object-Parameter an WorkflowDesignApi, und fügen Sie alles unter einem Try Catch hinzu, nur um sicherzustellen, dass alle Ausnahmen verwaltet werden.
• Sobald Sie die WorkflowDesignApi-API aufgelöst haben, ist WorkflowAnalyzerConfigService als Eigenschaft verfügbar.
• An diesem Punkt haben Sie Zugriff auf den im Abschnitt oben beschriebenen IAnalyzerConfigurationService.

Hinzufügen von Regeln zu Studio

Benutzerdefinierte Regeln für die Workflow-Analyse können auf zwei Arten in Studio integriert werden:

• auf globaler Ebene durch Hinzufügen des externen Assemblys (.dll) im Studio-Installationsverzeichnis
• auf Projektebene durch Installation des benutzerdefinierten Aktivitätenpakets.

Auf globaler Ebene

Um benutzerdefinierte Regeln in allen Projekten verfügbar zu machen, die in Ihrer Instanz von Studio erstellt werden, müssen Sie die externen Assembly-Pakete (.dll) zu einem bestimmten Ordner hinzufügen, aus dem Studio benutzerdefinierte Regeln lädt. Standardmäßig lautet der Ordnerpfad:

• In Studio-Versionen vor 2021.10:

  • For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules
  • Für Installationen pro Benutzer: %LocalAppData%\Programs\UiPath\Studio\Rules

• In Studio 2021.10.6 und höher:

  • Für Installationen pro Maschine: %ProgramFiles%\UiPath\Studio\Rules\net6.0 (für Regeln, die für Windows- und plattformübergreifende Projekte bestimmt sind) und %ProgramFiles%\UiPath\Studio\net461\Rules (für Regeln, die für Windows-Legacy-Projekte bestimmt sind)
  • Für Installationen pro Benutzer: %LocalAppData%\Programs\UiPath\Studio\Rules\net6.0 (für Regeln, die für Windows- und plattformübergreifende Projekte bestimmt sind) und %LocalAppData%\Programs\UiPath\Studio\net461\Rules (für Regeln, die für Windows-Legacy-Projekte bestimmt sind)

Optionally, you can change the folder from which Studio loads custom rules by going to Home (Studio Backstage View) > Settings > Locations and defining a Custom Workflow Analyzer rules location. This feature is available in Studio v2020.10. and later.

Führen Sie die auf der Seite Erstellen einer benutzerdefinierten Aktivität beschriebenen Schritte aus, um den Code als DLL-Datei zu exportieren.

Auf Projektebene

Um benutzerdefinierte Regeln nur für ein bestimmtes Projekt verfügbar zu machen, erstellen Sie ein NuGet-Paket (.nupkg), und installieren Sie es in einem Studio-Projekt als Abhängigkeit.