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, necesitas el paquete UiPath.Activities.Api de la fuente Oficial. El paquete SDK debe usarse como dependencia de desarrollo en tu proyecto personalizado. Consulta más detalles sobre las Dependencias de desarrollo.

Mira 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 Uso de The Activity Creator .

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 y posterior: .NET Framework 4.6.1 para proyectos Windows , .NET 6 para proyectos Windows y multiplataforma .

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.

Nota:

Al crear reglas y contadores personalizados, recomendamos seguir la convención de nomenclatura detallada en la página Acerca del analizador de flujo de trabajo .

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 nomenclatura de variables, Longitud de variable superada y Estadísticas de actividades de archivo son tres reglas listas para usar que se pueden establecer para inspeccionar actividades.
• Flujo de trabajo: se pueden establecer reglas o contadores para realizar comprobaciones en un solo archivo de proyecto. Recuento de argumentos alto y Secuencia vacía son solo dos reglas predefinidas que tienen el flujo de trabajo como ámbito.
• Proyecto: las comprobaciones se realizan a nivel de proyecto, garantizando que se cumple la fiabilidad del proyecto. Dependencias no utilizadas es una regla aplicada en el ámbito del proyecto.

Crear reglas

Desde la fuente Oficial (https://pkgs.dev.azure.com/uipath/Public.Feeds/_packaging/UiPath-Official/nuget/v3/index.json), instala el paquete UiPath.Activities.Api.

Para ayudarte a crear una regla personalizada, veamos una regla predefinida actual en el Analizador de flujo de trabajo, Longitud variable excedida. Esta regla comprueba si la longitud de las variables definidas 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 tu regla. En este ejemplo, la regla Longitud variable excedida lleva el ID de regla ST-NMG-008 y sigue la Convención de nomenclatura de reglas. Ten en cuenta que la convención de nomenclatura utilizada por las reglas disponibles de forma predeterminada 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 ligeramente cuando queremos crear reglas que contengan parámetros personalizables. Una de esas reglas es la Convención de nomenclatura de variables. Su elemento de inspección es actividad y lleva una expresión Regex predeterminada, que se puede cambiar.

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 las estadísticas de actividades de archivo como ejemplo de cómo se ven 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:

Invoca el método HasFeature en el IAnalyzerConfigurationService para registrar reglas para una versión de Studio específica.

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 nivel global creando un paquete NuGet (.nupkg) desde el ensamblado externo externo (.dll).
• a escala de proyecto, instalando el paquete de actividades personalizado.

A escala global

Para que las reglas personalizadas estén disponibles en todos los proyectos creados en tu instancia de Studio:

1. Crea un paquete NuGet (.nupkg) a partir de los paquetes de ensamblado externo (.dll).
2. Cargar el archivo .nupkg paquete a una fuente personalizada.
3. Crea una política en Automation Ops que implemente la fuente en Studio y aplique el .nupkg paquete con las reglas personalizadas. Para obtener más información, consulta Gestionar orígenes en la guía del usuario de Automation Ops.

Añadir manualmente los paquetes de ensamblado (.dll)

Importante:

Este método no se recomienda, ya que .dll los paquetes pueden ser bloqueados por el software antivirus.

Como alternativa, puedes añadir los paquetes de ensamblado externo (.dll) a una carpeta específica desde la que Studio carga las reglas 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)

Opcionalmente, puedes cambiar la carpeta desde la que Studio carga las reglas personalizadas yendo a Inicio (vista Backstage de Studio) > Configuración > Ubicaciones y definiendo una ubicación de reglas personalizadas del Analizador de flujo de trabajo. Esta característica está disponible en Studio v2020.10. y posteriores.

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

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.