Construir reglas para el Analizador de flujo de trabajo

El Analizador de flujo de trabajo es una herramienta que garantiza que tu proyecto cumple las mejores prácticas y los requisitos de mantenimiento, legibilidad, rendimiento, reusabilidad, fiabilidad y seguridad.

Estos conceptos son importantes para garantizar flujos de trabajo fluidos y fiables capaces de resumir grandes proyectos de automatización.

Nota: Para crear reglas personalizadas, necesita el paquete .Api de UiPath Activities de la fuente oficial . El paquete SDK debe usarse como una dependencia de desarrollo en tu proyecto personalizado. Más información sobre las dependencias de desarrollo.

Vea el siguiente vídeo para obtener instrucciones paso a paso sobre cómo crear reglas personalizadas y cómo crear actividades personalizadas con la extensión Usar el Creador de actividades .

En su forma comercial, el Analizador de flujo de trabajo se integra en Studio e incorpora capacidades de validación y analizador. Si la validación señala errores, no se puede realizar el análisis.

Conceptos del Analizador de flujo de trabajo

Para crear reglas personalizadas para tu proyecto, debes definir una serie de conceptos que permitan entender mejor cómo funciona el Analizador de flujo de trabajo en segundo plano.

Nota:

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

• Studio 2021.4 y versiones anteriores: .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.

Reglas y contadores

El Analizador de flujo de trabajo utiliza determinados criterios para garantizar la fiabilidad del proyecto. Estas comprobaciones se realizan por medio de reglas y contadores cuidadosamente definidos.

Una regla representa un requisito que debe cumplirse. Se puede establecer para cotejar el objeto de inspección con la definición de la regla.

Un contador representa una comprobación que se realiza para averiguar el número de veces que se ha producido un evento o condición concretos.

En el panel Lista de errores, aparece un mensaje para cada regla incumplida, en forma de advertencia, error, información o mensajes detallados. Estas listas también contienen recomendaciones para efectuar cambios y garantizar el cumplimiento de las normas.

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

Objeto de inspección

El Analizador de flujo de trabajo puede realizar un análisis en profundidad de un objeto predeterminado. El objeto representa el ámbito a analizar, el área en la que se aplica la regla o el contador.

• Actividad: es el objeto de inspección más pequeño. Por ejemplo, Convención de denominaciónde variables, Longitud de variable excediday Estadísticas de actividades de archivo son tres reglas listas para usar que se pueden configurar para inspeccionar actividades.
• Flujode trabajo: se pueden configurar reglas o contadores para realizar comprobaciones en un solo archivo de proyecto. Recuento alto de argumentos y Secuencia vacía son solo dos reglas predefinidas que tienen el flujo de trabajo como ámbito.
• Proyecto: se realizan comprobaciones a nivel de proyecto para garantizar que se cumple su fiabilidad. Las dependencias no utilizadas es una regla que se aplica en el ámbito del proyecto.

Crear reglas

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.

Para ayudarte a crear una regla personalizada, veamos una regla predefinida actual en el Analizador de flujo de trabajo, Longitud de variable sobrepasada. Esta regla comprueba si la longitud de las variables definida en el proyecto es inferior a 20 caracteres. El objeto de inspección de la regla es actividad.

En segundo plano, la regla es así:

// 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 };
            }
        }
    }

El parámetro RuleId requiere el nombre de su regla. En este ejemplo, la regla Longitud variable lleva el ID de regla ST-NMG-008 y sigue la Convención de denominación de reglas. Ten en cuenta que la convención de nomenclatura utilizada por las reglas disponibles por defecto en Studio no es obligatoria.

El parámetro RecommendationMessage exige que se muestre un mensaje en forma de recomendación para ayudar al usuario a resolver las incoherencias detectadas tras la realización del análisis. El mensaje debe ser breve e indicar pasos claros.

El parámetro ErrorLevel indica la medida predeterminada que se ha de adoptar en caso de que no se cumpla la condición. En este ejemplo, la regla lanza una advertencia. Las medidas predeterminadas pueden ser error, advertencia, información o detallado.

Crear reglas con parámetros

La situación cambia un poco cuando queremos crear reglas que contienen parámetros personalizables. Una de estas reglas es Convención de denominación de variables. Su elemento de inspección es actividad y lleva una expresión Regex predeterminada que se puede modificar.

En segundo plano, esta regla es así:

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 };
            }
        }
    }

Observa que invoca los parámetros RuleId, RegexKey y DefaultRegex, que es la expresión Regex predeterminada asociada a esta regla.

Los parámetros RecommendationMessage y ErrorLevel son los mismos que los de la regla presentada anteriormente.

Crear contadores

Los contadores representan comprobaciones realizadas para averiguar el número de veces que se ha producido un evento o una situación concretos.

Su estructura es un poco distinta a la de las reglas, en el sentido de que el único parámetro ErrorLevel disponible para los contadores es Info. Por lo tanto, la expresión para definir el nivel de error de un contador debe ser así ErrorLevel = System.Diagnostics.TraceLevel.Info.

Tomemos la regla Estadísticas de actividades de archivo como ejemplo de cómo son las reglas de contador en segundo plano:

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) }
            };
        }

Crear reglas para StudioX

De forma predeterminada, las reglas solo se aplican al perfil de Studio. Para que una regla aparezca también en el perfil de StudioX, añade la propiedad ApplicableScopes y configúrala para que incluya BusinessRule. Por ejemplo, puedes añadir la propiedad así:

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 }
            };

Registro de reglas

Método de interfaz de registro

Ten en cuenta que si utilizas este método, tu paquete solo es compatible con las versiones de Studio 2019.10 y posteriores.

Implementa la interfaz IRegisterAnalyzerConfiguration con el siguiente método 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());
        }
    }
}

Nota: Llame al método HasFeature en IAnalyzerConfigurationService para registrar reglas para una versión específica de Studio.

Método IRegisterMetadata

Ten en cuenta que este método solo está disponible para versiones de Studio posteriores a 2019.6 y que no es apto como método de interfaz de registro.

• Añade un Initialize(object api) vacío de método a tu implementación de IRegisterMetadata.
• En tu implementación Initialize, lanza el parámetro object para WorkflowDesignApi, y añádelo todo en un bloque Try Catch para gestionar todas las excepciones.
• Una vez que resuelvas la propiedad WorkflowDesignApi, WorkflowAnalyzerConfigService está disponible como propiedad.
• En este punto, tienes acceso al parámetro IAnalyzerConfigurationService, detallado en la sección anterior.

Añadir reglas a Studio

Las reglas personalizadas del Analizador de flujo de trabajo se pueden integrar en Studio de dos formas:

• a escala global, añadiendo el ensamblado externo (.dll) en la ubicación de instalación de Studio
• a escala de proyecto, instalando el paquete de actividades personalizado.

A escala global

Para hacer disponibles las reglas personalizadas en todos los proyectos creados en tu instancia de Studio, debes añadir los paquetes de ensamblado externo (.dll) a una carpeta específica desde la que Studio carga las normas personalizadas. De forma predeterminada, la ruta de la carpeta es:

• En versiones de Studio anteriores a 2021.10:

  • For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules
  • Para instalaciones por usuario: %LocalAppData%\Programs\UiPath\Studio\Rules

• En Studio 2021.10.6 y posterior:

  • For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules\net6.0 (for rules targetting Windows and cross-platform projects) and %ProgramFiles%\UiPath\Studio\net461\Rules (for rules targetting Windows-legacy projects)
  • For per-user installations: %LocalAppData%\Programs\UiPath\Studio\Rules\net6.0 (for rules targetting Windows and cross-platform projects) and %LocalAppData%\Programs\UiPath\Studio\net461\Rules (for rules targetting Windows-legacy projects)

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.

Siga los pasos detallados en la página Crear una actividad personalizada para exportar el código como .dll archivo.

A escala de proyecto

Para que las reglas personalizadas solo estén disponibles para un determinado proyecto, crea un paquete NuGet (.nupkg) e instálalo en un proyecto de Studio como dependencia.