Actions SDK көмегімен жұмыс үстеліндегі әрекеттер үшін Power Automate жасаңыз

Бұл мақалада жұмыс үстелі үшін Power Automate те реттелетін әрекеттерді жасау жолы сипатталған.

Реттелетін әрекеттерді жасау

Жаңа Class Library (.NET Framework) жобасын жасау арқылы бастаңыз. .NET Framework 4.7.2 нұсқасын таңдаңыз.

Жасалған теңшелетін модульде әрекетті қалыптастыру үшін:

• Автоматты түрде жасалған Class1.cs файлын жойыңыз.
• Теңшелетін әрекетті көрсету үшін жобаңызда жаңа класс жасаңыз, оған нақты атау беріңіз.
• Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK және Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes аттар кеңістіктерін қосыңыз.
• Әрекеттерді білдіретін барлық сыныптарда сыныптың үстінде [Әрекет] төлсипаты болуы керек.
• Сыныптың жалпы қолжетімділігі болуы және 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# сипаттарымен ұсынылған. Әрбір сипаттың түрін және жұмыс үстелі үшін [InputArgument] көрсетілу жолын белгілеу үшін [OutputArgument] немесе Power Automate сәйкес C# төлсипаты болуы керек. Енгізу аргументтерінің әдепкі мәндері де болуы мүмкін.

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" деп аталу керек.

Модульдер мен әрекеттерге арналған сипаттамалардың пішімі келесідей болуы керек:

Атау өрісінде сәйкесінше "Модул_Сипаттамасы" немесе "Әрекет_Сипаттамасы" және "Модул_ДұрысАты" немесе "Әрекет_ДұрысАты". Мән өрісіндегі сипаттама.

Сондай-ақ параметрлер үшін сипаттамалар мен түсінікті атауларды беруді ұсынамыз. Олардың пішімі келесідей болуы керек: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Оларды сондай-ақ [InputArgument], [OutputArgument] және [Action] атрибуттарының FriendlyName және Сипаттама сипаттарымен орнатуға болады.

Мұнда теңшелетін модульге арналған Resources.resx файлының мысалы берілген.

Әрекеттер мен параметрлерге түсінікті атаулар мен сипаттамаларды жылдам қосудың тағы бір жолы — [Action] [InputArguement] және [OutputArguement] атрибуттарындағы "FriendlyName" және "Description" сипаттары.

Теңшелетін әрекеттерге қателерді өңдеуді қосу

Әрекетіңізде реттелетін ерекше жағдайларды анықтау үшін теңшелетін әрекет сыныбының үстіндегі [Throws("ActionError")] төлсипатын пайдаланыңыз. Анықтағыңыз келетін әрбір ерекше жағдайдың өз төлсипаты болуы керек.

Catch блогында келесі кодты пайдаланыңыз:

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

ActionException атының Throws атрибутында берген атқа сәйкес келетініне көз жеткізіңіз. Әрбір ерекше жағдай үшін throw new ActionException пайдаланыңыз және оны сәйкес Throws атрибут атауымен сәйкестендіріңіз. Throws атрибутымен анықталған барлық ерекшеліктер дизайнердің әрекет қатесін өңдеу қойындысында көрінеді.

Мұның мысалын Шартты әрекеттер бөлімінен табуға болады.

Ресурстарды локализациялау

Жұмыс үстеліне арналған Power Automate модульдердің әдепкі тілі ағылшын тілі болып есептеледі.

Resources.resx файл ағылшын тілінде болуы керек.

Кез келген басқа тілдерді локализация үшін қосымша ресурстармен қосуға болады.{locale}.resx файлдары. Мысалы, Resources.fr.resx.

Арнаулы модуль санаттары

Әрекетті жақсы ұйымдастыру үшін модульдер санаттар мен ішкі санаттарды қамтуы мүмкін.

Санаттарда, ішкі санаттарда теңшелетін әрекеттерді бөлу үшін теңшелетін әрекетті көрсететін сыныптың алдындағы [Әрекет] атрибутын келесі жолмен өзгертіңіз:

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

Тапсырыс сипаты конструкторда әрекеттерді алдын ала қарау ретін белгілейді.

Action1 «TestCategory» санатына жатады және бұл модульдің бірінші әрекеті (осылайша сіз тәртіп пен санатты мысалмен түсіндіресіз).

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

Шартты әрекеттер

Шартты әрекеттер – «ақиқат» немесе «жалған» мәндерін қайтаратын әрекеттер. Стандартты кітапхананың жұмыс үстеліндегі әрекеті үшін 'файл бар болса' 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
    }
}

Нәтиже логикалық айнымалы мәніне назар аударыңыз.

Егер файл бар болса әрекетінде шығыс аргументі жоқ. Оның қайтаратыны логикалық айнымалы Нәтиже орындайтынына байланысты ақиқат немесе жалған болады.

Теңшелетін әрекет селекторлары

Теңшелетін әрекетте бірнеше нұсқа болуы талап етілетін нақты жағдайлар бар.

Мысал ретінде стандартты әрекеттер кітапханасындағы «Excel іске қосу» әрекетін келтіруге болады.

«Бос құжатпен» селекторын пайдалану ағыны бос Excel құжатын іске қосады, ал «және келесі құжатты ашу» таңдауын пайдалану файлдың файл жолын ашуды талап етеді.

Жоғарыда аталған екі әрекет «Excel іске қосу» негізгі әрекетінің екі селекторы болып табылады.

Теңшелетін әрекеттерді жасаған кезде функционалдылықты қайта жазудың қажеті жоқ.

Сіз оның кіріс және шығыс параметрлерін орната отырып, бір "негізгі" әрекетті жасай аласыз, содан кейін әрекет селекторларын пайдалану арқылы әр дәмде көрінетін нәрсені таңдай аласыз.

Әрекет селекторлары арқылы әр уақытта бірдей әрекеттің жаңа нұсқасын қалыптастыру үшін кодты қайта жазудың қажеті жоқ, бір "негіз" әрекетінен нақты функционалдылықты алуға мүмкіндік беретін абстракция деңгейін бір әрекетке қосуға болады.

Селекторларды таңдаулар, бір әрекетті сүзу және сәйкес селекторларға сәйкес талап етілетін ақпаратты ғана ұсыну ретінде қарастырыңыз.

Жаңа әрекет селекторын қалыптастыру үшін алдымен селекторлар пайдаланатын негізгі әрекетті жасаңыз.

Орталық әрекет C# кіріс аргументі ретінде логикалық немесе enum сипатын қажет етеді.

Бұл сипаттың мәні қандай селектордың пайдаланылатынын анықтайды.

Ең көп таралған әдіс - enum пайдалану. Әсіресе екіден көп селектор қажет болғанда, нөмірлер жалғыз опция болып табылады.

Екі селекторлық жағдай үшін логикалық мәндерді пайдалануға болады.

Шектеу аргументі ретінде белгілі бұл сипат әдепкі мәнге ие болуы керек.

Орталық әрекет классикалық әрекет ретінде жарияланады.

Назар аударыңыз, бірінші сипат (енгізу аргументі) санау болып табылады. Осы сипаттың мәніне негізделген сәйкес селектор белсенді болады.

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
}

Санақтарды қолданатын теңшелетін әрекетті таңдаушылар

Бұл мысалда сіз үш селектор жасайсыз. Қарапайым нөмір әр уақытта сәйкес селекторды белгілейді:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Селекторлар сыныптармен ұсынылған.

Бұл сыныптар ActionSelector<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);
    }
}

Осы нақты мысалда біз аргументтердің біреуін ғана көрсеткіміз келеді, осылайша басқалары сүзгіден өткізіледі. Сол сияқты Selector2 үшін:

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

Логикалық көмегімен теңшелетін әрекет селекторлары

Төменде сандардың орнына логикалық мәнді қолданатын мысал келтірілген.

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 әдістерімен де жасауға болады.

Теңшелетін модуль идентификаторлары

Әрбір модульдің өз идентификаторы (жинақ атауы) болады. Пайдаланушы модульдерін жасаған кезде бірегей модуль идентификаторларын орнатқаныңызға көз жеткізіңіз. Модульдің құрастыру атын орнату үшін C# жобасының сипаттарының Жалпы бөліміндегі Ассамблея атауы сипатты өзгертіңіз.

Теңшелетін модуль атауы конвенциялары

Теңшелетін модульдер жұмыс үстелі үшін Power Automate арқылы оқылатын болуы үшін AssemblyName төмендегі үлгіге сәйкес файл атауы болуы керек:

?*.Modules.?*
Modules.?*

Мысалы, Модульдер.ContosoActions.dll

Жоба параметрлеріндегі AssemblyTitle модуль идентификаторын көрсетеді. Онда тек әріптік-сандық таңбалар мен астыңғы сызықтар болуы мүмкін және әріптен басталуы керек.

Пайдаланушы модулінің ішіндегі барлық DLL файлдарына қол қойыңыз

Пайдаланушы модулін жасауды аяқтау үшін жобаның бин/шығару немесе bin/Debug қалтасынан табуға болатын барлық жасалған .dll файлдарына қол қою керек.

Visual Studioүшін әзірлеуші ​​пәрмен жолында келесі пәрменді (әр .dll файлы үшін) орындау арқылы сенімді сертификатты пайдаланып барлық .dll файлдарына қол қойыңыз:

Visual Studioүшін әзірлеуші ​​пәрмен жолында келесі пәрменді (әр DLL үшін) іске қосу арқылы сенімді сертификатты пайдаланып .dlls файлдарына қол қойыңыз:

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

немесе барлық .dll файлдары арқылы қайталанатын және әрқайсысына берілген сертификатпен қол қоятын келесі пәрменді іске қосу (Windows PowerShell Script .ps1 жасау арқылы):

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) бумалануы керек.

Келесі жолдарды қамтитын 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

Келесі қадамдар

Арнаулы әрекеттерді жүктеп салу

Қатысты ақпарат

• Активтер кітапханасы
• Арнаулы әрекеттерді пайдаланыңыз
• Арнаулы әрекеттер