Създаване Power Automate на действия за работен плот с помощта на SDK за действия

Статия
08/05/2024

Тази статия описва как да създавате персонализирани действия за Power Automate настолен компютър.

Създаване на персонализирани действия

Важно

Запазените ключови думи не могат да се използват като имена на действия и/или свойства на действие. Използването на запазени ключови думи като имена на действия и/или свойства на действие води до погрешно поведение. Повече информация: Запазени ключови думи в потоци на работния плот

Започнете със създаване на нов проект за библиотека на класове (.NET Framework). Изберете .NET framework версия 4.7.2.

За да оформите действие в създадения персонализиран модул:

Изтрийте автоматично генерирания Class1.cs файл.
Създайте нов клас във вашия проект, за да представите персонализираното действие, дайте му различно име.
Включете пространствата от имена Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK и Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes.
Всички класове, представляващи действия, трябва да имат атрибут [Action] над вашия клас.
Класът трябва да има публичен достъп и да наследява от класа ActionBase.

using System;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes;

namespace Modules.MyCustomModule
{
    [Action(Id = "CustomAction")]
    public class CustomAction : ActionBase
    {
        public override void Execute(ActionContext context)
        {
            throw new NotImplementedException();
        }
    }
}

Повечето действия имат параметри (вход или изход). Входните и изходните параметри са представени от класически C# свойства. Всяко свойство трябва да има подходящ C# атрибут, или [InputArgument] [OutputArgument] за да диктува неговия тип и как да се представят Power Automate за настолен компютър. Входните аргументи също могат да имат стойности по подразбиране.

using System.ComponentModel;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes;

namespace Modules.MyCustomModule
{
    [Action(Id = "CustomAction")]
    public class CustomAction : ActionBase
    {
        [InputArgument, DefaultValue("Developer")]
        public string InputName { get; set; }

        [OutputArgument]
        public string DisplayedMessage { get; set; }

        public override void Execute(ActionContext context)
        {
            DisplayedMessage = $"Hello, {InputName}";
        }
    }
}

Добавяне на описания към персонализирани действия

Добавете описание и приятелско име за модулите и действията, така че разработчиците на RPA да знаят как най-добре да ги използват.

Power Automate за настолен дизайнер показва удобни имена и описания.

Можете да създадете файл "Resources.resx" в папката "Свойства" на проекта на модула. Новият файл ".resx" трябва да бъде наречен "Resources.resx".

Форматът на описанията на модулите и действията трябва да бъде следният:

"Module_Description" или "Action_Description" и "Module_FriendlyName" или "Action_FriendlyName" съответно в полето за име. Описанието в полето за стойност.

Препоръчваме ви също да предоставите описания и удобни имена за параметри. Форматът им трябва да бъде следният: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Екранна снимка на Ресурси за просто действие

Съвет

Препоръчително е да обозначите това, което описвате в полето за коментар (напр. модул, действие и т.н.)

Те също могат да бъдат зададени със свойствата FriendlyName и Description на атрибутите [InputArgument] и [OutputArgument] [Action] .

Ето пример за Resources.resx файл за персонализиран модул.

Екранна снимка на ресурси

Друг начин за бързо добавяне на приятелски имена и описания към действия и параметри е със свойствата FriendlyName и Description в атрибутите [Action]and [InputArguement] [OutputArguement] .

Бележка

За да добавите приятелско име и описание към модул, трябва да промените съответния .resx файл или да добавите съответните C# атрибути.

Локализация на ресурси

Езикът по подразбиране за модули за Power Automate настолен компютър се приема за английски.

Файлът Resources.resx трябва да е на английски език.

Всички други езици могат да бъдат добавени с допълнителни ресурси.{locale} resx файлове за локализация. Например, Resources.fr.resx.

Персонализирани категории модули

Модулите могат да включват категории и подкатегории за по-добра организация на действията.

За да разделите персонализираните действия в категории, подкатегории, променете атрибута[Action] , който предхожда класа, който представлява персонализираното действие, по следния начин:

[Action(Category = "category.subcategory")]

Бележка

Модулът може да има няколко категории. По същия начин категориите могат да бъдат съставени от подкатегории. Тази структура може да бъде неопределена.

Свойството Order диктува реда, по който действията се визуализират в дизайнера.

Action1 принадлежи към категорията "TestCategory" и това е първото действие на модула (по този начин обяснявате Order и category с пример).

[Action(Id = "Action1", Order = 1, Category = "TestCategory")]

Условни действия

Условните действия са действия, които връщат "True" или "False". "Ако файлът съществува" Power Automate за действието на работния плот на стандартната библиотека е добър пример за условно действие.

Пример за условно действие:

using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes;
using System;
using System.ComponentModel;

namespace Modules.CustomModule
{
    [ConditionAction(Id = "ConditionalAction1", ResultPropertyName = nameof(Result))]
    [Throws("ActionError")] // TODO: change error name (or delete if not needed)
    public class ConditionalAction1 : ActionBase
    {
        #region Properties

        public bool Result { get; private set; }

        [InputArgument]
        public string InputArgument1 { get; set; }

        #endregion

        #region Methods Overrides

        public override void Execute(ActionContext context)
        {
            try
            {
                //TODO: add action execution code here
            }
            catch (Exception e)
            {
                if (e is ActionException) throw;

                throw new ActionException("ActionError", e.Message, e.InnerException);
            }
        }

        #endregion
    }
}

Обърнете внимание на булевата променлива Резултат .

Действието Ако файлът съществува няма изходен аргумент. Това, което връща, е вярно или невярно, в зависимост от това какво съдържа булевата променлива Result .

Персонализирани селектори на действия

Има конкретни случаи, в които може да се изисква персонализирано действие да има повече от един вариант.

Пример за това е действието "Стартиране на Excel" от стандартната библиотека от действия.

С помощта на селектора "с празен документ" потокът стартира празен документ на Excel, докато използването на избора "и отворете следния документ" изисква пътя на файла да се отвори.

Екранна снимка на селекторите за действие за стартиране на Excel

Двете действия, споменати по-горе, са два селектора на базовото действие "Стартиране на Excel".

Когато създавате персонализирани действия, не е нужно да пренаписвате функционалността.

Можете да създадете едно "базово" действие, като зададете неговите входни и изходни параметри и след това да изберете какво ще се вижда във всеки вкус, като използвате селектори за действие.

Чрез селекторите на действия може да се добави ниво на абстракция върху едно действие, което позволява извличането на специфична функционалност от единственото "базово" действие, без да се налага да се пренаписва код, за да се формира нов вариант на едно и също действие всеки път.

Мислете за селекторите като за избори, филтриращи едно действие и представящи само информацията, необходима според съответните селектори.

Екранна снимка на диаграмата на селекторите на действия

За да оформите нов селектор на действие, първо създайте основно действие, което да се използва от селекторите.

Централното действие изисква или булево или изброяване свойство като входен C# аргумент.

Стойността на това свойство определя кой селектор да се използва.

Най-често срещаният начин е използването на изброяване. Особено когато са необходими повече от два селектора, enums е единствената опция.

За два случая на селектор могат да се използват булеви стойности.

Това свойство, известно още като аргумент на ограничението, трябва да има стойност по подразбиране.

Централното действие се обявява за класическо действие.

Забележете, че първото свойство (входен аргумент) е изброяване. Въз основа на стойността на това свойство подходящият селектор става активен.

Бележка

За да подредите аргументите по желания от вас начин, задайте стойността Order до атрибута InputArgument.

using System.ComponentModel;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Desktop.Actions.SDK;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Desktop.Actions.SDK.Attributes;

namespace Modules.CustomModule
{
    [Action(Id = "CentralCustomAction")]
    public  class CentralCustomAction : ActionBase
    {
        #region Properties

        [InputArgument, DefaultValue(SelectorChoice.Selector1)]
        public SelectorChoice Selector { get; set; }

        [InputArgument(Order = 1)]
        public string FirstName { get; set; }

        [InputArgument(Order = 2)]
        public string LastName { get; set; }

        [InputArgument(Order = 3)]
        public int Age { get; set; }

        [OutputArgument]
        public string DisplayedMessage { get; set; }

        #endregion

        #region Methods Overrides

        public override void Execute(ActionContext context)
        {
            if (Selector == SelectorChoice.Selector1)
            {
                DisplayedMessage = $"Hello, {FirstName}!";
            }
            else if (Selector == SelectorChoice.Selector2)
            {
                DisplayedMessage = $"Hello, {FirstName} {LastName}!";
            }
            else // The 3rd Selector was chosen 
            {
                DisplayedMessage = $"Hello, {FirstName} {LastName}!\nYour age is: {Age}";
            }
        }

        #endregion
    } // you can see below how to implement an action selector
}

Персонализирани селектори на действия, използващи enums

В този пример създавате три селектора. Просто изброяване диктува подходящия селектор всеки път:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Селекторите са представени по класове.

Тези класове трябва да наследят класа ActionSelector<TBaseActionClass> .

Бележка

TBaseActionClass е името на базовия клас на действието.

В метода UseName() се декларира името на селектора на действие. Това се използва като име на действието за разрешаване на ресурсите.

public class Selector1 : ActionSelector<CentralCustomAction>
{
    public Selector1()
    {
        UseName("DisplayOnlyFirstName");
        Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector1);
        ShowAll();
        Hide(p => p.LastName);
        Hide(p => p.Age);
        // or 
        // Show(p => p.FirstName); 
        // Show(p => p.DisplayedMessage);
    }
}

Бележка

Класовете Selector не трябва да се декларират като действия. Единственото действие е централното. Селекторите действат като филтри.

В този конкретен пример искаме да покажем само един от аргументите, като по този начин останалите се филтрират. По същия начин за селектор2:

public class Selector2 : ActionSelector<CentralCustomAction>
{
    public Selector2()
    {
        UseName("DisplayFullName");
        Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector2);
        ShowAll();
        Hide(p => p.Age);
    }
}

И класове Selector3 :

public class Selector3 : ActionSelector<CentralCustomAction>
{
    public Selector3()
    {
        UseName("DisplayFullDetails");
        Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector3);
        ShowAll();
    }
}

Окончателното изпълнение се постига чрез метода Execute(ActionContext context), който се намира в централното действие. Въз основа на селектора се показват съответните филтрирани стойности.

public override void Execute(ActionContext context)
{
    if (Selector == SelectorChoice.Selector1)
    {
        DisplayedMessage = $"Hello, {FirstName}!";
    }
    else if (Selector == SelectorChoice.Selector2)
    {
        DisplayedMessage = $"Hello, {FirstName} {LastName}!";
    }
    else // The 3rd Selector was chosen 
    {
        DisplayedMessage = $"Hello, {FirstName} {LastName}!\nYour age is: {Age}";
    }
}

Персонализирани селектори на действия, използващи булеви стойности

Следва пример за използване на булева стойност вместо enums.

using System.ComponentModel;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.ActionSelectors;
using Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes;

namespace Modules.CustomModule
{
    [Action]
    public class CentralCustomActionWithBoolean : ActionBase
    {
        #region Properties

        [InputArgument, DefaultValue(true)]
        public bool TimeExpired { get; set; }

        [InputArgument]
        public string ElapsedTime { get; set; }

        [InputArgument]
        public string RemainingTime { get; set; }

        [OutputArgument]
        public string DisplayedMessage { get; set; }

        #endregion

        #region Methods Overrides

        public override void Execute(ActionContext context)
        {
            DisplayedMessage = TimeExpired ? $"The timer has expired. Elapsed time: {ElapsedTime}" : $"Remaining time: {RemainingTime}";
        }

        #endregion
    }

    public class NoTime : ActionSelector<CentralCustomActionWithBoolean>
    {
        public NoTime()
        {
            UseName("TimeHasExpired");
            Prop(p => p.TimeExpired).ShouldBe(true);
            ShowAll();
            Hide(p => p.RemainingTime);
        }
    }

    public class ThereIsTime : ActionSelector<CentralCustomActionWithBoolean>
    {
        public ThereIsTime()
        {
            UseName("TimeHasNotExpired");
            Prop(p => p.TimeExpired).ShouldBe(false);
            ShowAll();
            Hide(p => p.RemainingTime);
        }
    }
}

Задаване на описания за персонализирани селектори на действия

За да създадете описание и обобщение за селектори, използвайте следния формат в .resx файла на вашия персонализиран модул.

SelectorName_Description
SelectorName_Summary

Това може да се направи и в селектора с методите WithDescription и WithSummary.

Важно

.dll файлове, описващи персонализираните действия, техните .dll зависимости и .cab файл, съдържащ всичко, трябва да бъдат правилно подписани с цифров сертификат, на който вашата организация се доверява. Сертификатът трябва да бъде инсталиран и на всяка машина, на която е създаден/модифициран/изпълнен поток за работен плот с персонализирани зависимости от действия, присъстващ в Trusted Root Certification Authority.

Персонализирани идентификатори на модули

Всеки модул има свой собствен идентификатор (име на сглобката). Когато създавате персонализирани модули, уверете се, че сте задали уникални идентификатори на модули. За да зададете името на сглобката на вашия модул, променете свойството Име на сглобката в раздела Общи на свойствата на проекта C#.

Предупреждение

Включването на модули с еднакъв идентификатор в поток ще доведе до конфликти

Потребителски конвенции за имена на модули

За да могат персонализираните модули да могат да се четат Power Automate за настолен компютър, AssemblyName трябва да има име на файл, което следва модела по-долу:

?*.Modules.?*
Modules.?*

Например модули. ContosoActions.dll

AssemblyTitle в настройките на проекта определя ИД на модула. Може да има само буквено-цифрови знаци и долни черти и трябва да започва с буква.

Подпишете всички DLL файлове в персонализирания модул

Важно

Задължително е всички .dll файлове да се състоят от персонализиран модул (генериран монтаж и всички негови зависимости), подписан с доверен сертификат

За да се финализира създаването на персонализирания модул, всички генерирани .dll файлове, които могат да бъдат намерени в папката bin/release или bin/Debug на проекта, трябва да бъдат подписани.

Подпишете всички .dll файлове с надежден сертификат, като изпълните следната команда (за всеки .dll файл) в командния ред за разработчици за Visual Studio:

Подпишете .dlls файловете с помощта на надежден сертификат, като изпълните следната команда (за всяка dll) в командния ред на разработчиците за: Visual Studio

Signtool sign /f {your certificate name}.pfx /p {your password for exporting the certificate} /fd 
SHA256 {path to the .dll you want to sign}.dll

или като изпълните следната команда (чрез създаване на Windows PowerShell скрипт .ps1), която обхожда всички .dll файлове и подписва всеки от тях с предоставения сертификат:

Get-ChildItem {the folder where dll files of custom module exist} -Filter *.dll | 
Foreach-Object {
	Signtool sign /f {your certificate name}.pfx /p {your password for exporting the certificate} /fd SHA256 $_.FullName
}

Бележка

Цифровият сертификат трябва да има възможности за експортируем частен ключ и кодов знак

Опаковане на всичко в шкаф

.dll, съдържащ персонализираните действия и всички негови зависимости (.dll файлове), трябва да бъде опакован във файл на шкафа (.cab).

Бележка

Когато именувате файла .cab, следвайте конвенцията за именуване на файлове и папки за операционна система Windows. Не използвайте празни интервали или специални знаци като < > : " / \ | ? * .

Създайте скрипт на Windows PowerShell (.ps1), съдържащ следните редове:

param(

    [ValidateScript({Test-Path $_ -PathType Container})]
	[string]
	$sourceDir,
	
	[ValidateScript({Test-Path $_ -PathType Container})]
    [string]
    $cabOutputDir,

    [string]
    $cabFilename
)

$ddf = ".OPTION EXPLICIT
.Set CabinetName1=$cabFilename
.Set DiskDirectory1=$cabOutputDir
.Set CompressionType=LZX
.Set Cabinet=on
.Set Compress=on
.Set CabinetFileCountThreshold=0
.Set FolderFileCountThreshold=0
.Set FolderSizeThreshold=0
.Set MaxCabinetSize=0
.Set MaxDiskFileCount=0
.Set MaxDiskSize=0
"
$ddfpath = ($env:TEMP + "\customModule.ddf")
$sourceDirLength = $sourceDir.Length;
$ddf += (Get-ChildItem $sourceDir -Filter "*.dll" | Where-Object { (!$_.PSIsContainer) -and ($_.Name -ne "Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.dll") } | Select-Object -ExpandProperty FullName | ForEach-Object { '"' + $_ + '" "' + ($_.Substring($sourceDirLength)) + '"' }) -join "`r`n"
$ddf | Out-File -Encoding UTF8 $ddfpath
makecab.exe /F $ddfpath
Remove-Item $ddfpath

След това този скрипт на Windows PowerShell може да се използва за създаване на файла .cab, като го извикате в Windows PowerShell и предоставите:

Директорията към .dll файлове, които трябва да бъдат компресирани.
Целевата директория за поставяне на генерирания .cab файл.

Извикайте скрипта, като използвате следния синтаксис:

.\{name of script containing the .cab compression directions}.ps1 "{absolute path  to the source directory containing the .dll files}" "{target dir to save cab}" {cabName}.cab

Пример:

.\makeCabFile.ps1 "C:\Users\Username\source\repos\MyCustomModule\bin\Release\net472" "C:\Users\Username\MyCustomActions" MyCustomActions.cab

Бележка

Уверете се, че действителните персонализирани действия .dll файла са в основното ниво на целевия път, когато създавате файла .cab, а не във подпапка.
Досието .cab също трябва да бъде подписано. Неподписани .cab файлове и/или неподписани .dll, съдържащи се в тях, няма да могат да се използват в потоци на работния плот и ще доведат до грешка по време на включването.

Следващи стъпки

Качване на персонализирани действия

Споделяне чрез

Създаване Power Automate на действия за работен плот с помощта на SDK за действия

Създаване на персонализирани действия

Добавяне на описания към персонализирани действия

Локализация на ресурси

Персонализирани категории модули

Условни действия

Персонализирани селектори на действия

Персонализирани селектори на действия, използващи enums

Персонализирани селектори на действия, използващи булеви стойности

Задаване на описания за персонализирани селектори на действия

Персонализирани идентификатори на модули

Потребителски конвенции за имена на модули

Подпишете всички DLL файлове в персонализирания модул

Опаковане на всичко в шкаф

Следващи стъпки

Обратна връзка

Допълнителни ресурси

Споделяне чрез

Създаване Power Automate на действия за работен плот с помощта на SDK за действия

Създаване на персонализирани действия

Добавяне на описания към персонализирани действия

Локализация на ресурси

Персонализирани категории модули

Условни действия

Персонализирани селектори на действия

Персонализирани селектори на действия, използващи enums

Персонализирани селектори на действия, използващи булеви стойности

Задаване на описания за персонализирани селектори на действия

Персонализирани идентификатори на модули

Потребителски конвенции за имена на модули

Подпишете всички DLL файлове в персонализирания модул

Опаковане на всичко в шкаф

Следващи стъпки

Свързана информация

Обратна връзка

Допълнителни ресурси