Darbalaukio veiksmų kūrimas Power Automate naudojant veiksmų SDK

Šiame straipsnyje aprašoma, kaip sukurti pasirinktinius veiksmus Power Automate darbalaukiui.

Pasirinktinių veiksmų kūrimas

Pradėkite kurdami naują klasės bibliotekos (.NET Framework) projektą. Pasirinkite .NET Framework 4.7.2 versiją.

Norėdami suformuoti veiksmą sukurtame pasirinktiniame modulyje:

• Ištrinkite automatiškai sugeneruotą Class1.cs failą.
• Sukurkite naują klasę savo projekte, kad atspindėtumėte pasirinktinį veiksmą, suteikite jai atskirą pavadinimą.
• Įtraukite Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK ir Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes vardų sritis.
• Visos veiksmais žyminčios klasės turi turėti atributą [Veiksmas] virš jūsų klasės.
• Klasė turėtų turėti viešą prieigą ir paveldėti iš "ActionBase" klasės.

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

Dauguma veiksmų turi parametrus (įvestis arba išvestis). Įvesties ir išvesties parametrus vaizduoja klasikinės C# savybės. Kiekviena ypatybė turi turėti atitinkamą C# atributą arba [InputArgument] [OutputArgument] diktuoti jos tipą ir tai, kaip ji pateikiama Power Automate staliniams kompiuteriams. Įvesties argumentai taip pat gali turėti numatytąsias reikšmes.

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

Aprašų įtraukimas į pasirinktinius veiksmus

Pridėkite modulių ir veiksmų aprašymą ir draugišką pavadinimą, kad RPA kūrėjai žinotų, kaip geriausiai juos panaudoti.

Power Automate darbalaukio dizaino įrankiui rodomi draugiški vardai ir aprašai.

Galite sukurti "Resources.resx" failą modulio projekto aplanke Ypatybės. Naujasis ".resx" failas turėtų būti pavadintas "Resources.resx".

Modulių ir veiksmų aprašymų formatas turėtų būti toks:

"Module_Description" arba "Action_Description" ir "Module_FriendlyName" arba "Action_FriendlyName" atitinkamai pavadinimo lauke. Aprašymas reikšmės lauke.

Taip pat rekomenduojame pateikti parametrų aprašymus ir draugiškus pavadinimus. Jų formatas turėtų būti toks: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Juos taip pat galima nustatyti naudojant atributų "FriendlyName" ir "Description" ypatybes [InputArgument] [OutputArgument] . [Action]

Čia pateikiamas pasirinktinio modulio Resources.resx failo pavyzdys.

Kitas būdas greitai pridėti draugiškus pavadinimus ir aprašus prie veiksmų ir parametrų yra ypatybės FriendlyName ir Aprašas, esančios [Veiksmas], [InputArguement] ir [OutputArguement] atributai.

Klaidų tvarkymo įtraukimas į pasirinktinius veiksmus

Norėdami apibrėžti pasirinktines veiksmo išimtis, naudokite atributą [Throws("ActionError")] virš pasirinktinės veiksmų klasės. Kiekvienas išimties atvejis, kurį norite apibrėžti, turėtų turėti savo atributą.

Sugavimo bloke naudokite šį kodą:

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

Įsitikinkite, kad ActionException vardas atitinka vardą, kurį nurodėte atribute Throws . Naudokite throw new ActionException kiekvienam išimties atvejui ir suderinkite jį su atitinkamu Throws atributo pavadinimu. Visos išimtys, apibrėžtos naudojant atributą, Throws matomos dizaino įrankio veiksmo klaidų tvarkymo skirtuke.

To pavyzdį galima rasti skyriuje Sąlyginiai veiksmai .

Išteklių lokalizavimas

Laikoma, kad numatytoji darbalaukio modulių Power Automate kalba yra anglų.

Failas Resources.resx turėtų būti anglų kalba.

Bet kurias kitas kalbas galima pridėti naudojant papildomus išteklius.{locale}. resx failai lokalizavimui. Pavyzdžiui, Resources.fr.resx.

Pasirinktinių modulių kategorijos

Moduliai gali apimti kategorijas ir subkategorijas, kad būtų galima geriau organizuoti veiksmus.

Norėdami atskirti pasirinktinius veiksmus kategorijose, subkategorijose, modifikuokite atributą [Veiksmas], kuris yra prieš klasę, kuri atitinka pasirinktinį veiksmą, tokiu būdu:

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

Užsakymo ypatybė diktuoja tvarką, pagal kurią dizaino įrankyje peržiūrimi veiksmai.

Action1 priklauso kategorijai "TestCategory" ir tai yra pirmasis modulio veiksmas (tokiu būdu jūs paaiškinate užsakymą ir kategoriją pavyzdžiu).

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

Sąlyginiai veiksmai

Sąlyginiai veiksmai yra veiksmai, kurie pateikia "True" arba "False". "Jei yra failas", Power Automate skirtas standartinės bibliotekos darbalaukio veiksmui, yra geras sąlyginio veiksmo pavyzdys.

Sąlyginio veiksmo pavyzdys:

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

Atkreipkite dėmesį į rezultatą Bulio logikos kintamąjį.

Veiksmas Jei failas yra , neturi išvesties argumento. Tai, ką jis grąžina, yra teisinga arba klaidinga, atsižvelgiant į tai, ką turi Bulio logikos kintamasis Rezultatas .

Pasirinktiniai veiksmų parinkikliai

Yra ypatingų atvejų, kai pasirinktinis veiksmas gali turėti daugiau nei vieną variantą.

Pavyzdys yra veiksmas "Paleisti" Excel "iš standartinės veiksmų bibliotekos.

Naudojant parinkiklį "su tuščiu dokumentu", srautas paleidžia tuščią "Excel" dokumentą, o naudojant pasirinkimą "ir atidaryti šį dokumentą" reikia atidaryti failo kelią.

Du aukščiau paminėti veiksmai yra du pagrindinio veiksmo "Launch Excel" parinkikliai.

Kuriant pasirinktinius veiksmus nereikia perrašyti funkcijų.

Galite sukurti vieną "bazinį" veiksmą, nustatydami jo įvesties ir išvesties parametrus, tada pasirinkdami, kas būtų matoma kiekviename skonyje, naudodami veiksmų parinkiklius.

Naudojant veiksmų parinkiklius, abstrakcijos lygis gali būti pridėtas prie vieno veiksmo, leidžiantis gauti konkrečias funkcijas iš vieno "bazinio" veiksmo, nereikia perrašyti kodo, kad kiekvieną kartą būtų suformuotas naujas to paties veiksmo variantas.

Galvokite apie selektorius kaip apie pasirinkimus, filtruojančius vieną veiksmą ir pateikiančius tik tą informaciją, kurios reikia pagal atitinkamus selektorius.

Norėdami suformuoti naują veiksmų išrinkiklį, pirmiausia sukurkite pagrindinį veiksmą, kurį naudos parinkikliai.

Pagrindiniam veiksmui reikia Bulio logikos arba išvardijimas ypatybės kaip įvesties C# argumento.

Šios ypatybės vertė nustato, kuris parinkiklis naudojamas.

Dažniausias būdas yra išvardijimas naudojimas. Ypač kai reikia daugiau nei dviejų selektorių, vienintelė galimybė yra išvardijimai.

Dviem selektoriaus atvejams galima naudoti bulio logiką.

Ši ypatybė, dar vadinama apribojimo argumentu, turi turėti numatytąją reikšmę.

Pagrindinis veiksmas deklaruojamas kaip klasikinis veiksmas.

Atkreipkite dėmesį, kad pirmoji ypatybė (įvesties argumentas) yra išvardijimas. Atsižvelgiant į tos ypatybės vertę, atitinkamas parinkiklis tampa aktyvus.

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
}

Pasirinktiniai veiksmų parinkikliai, naudojantys išvardijimus

Šiame pavyzdyje sukuriate tris parinkiklius. Paprastas išvardijimas kiekvieną kartą padiktuoja tinkamą selektorių:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Selektorius atstovauja klasės.

Šios klasės turi paveldėti ActionSelector<TBaseActionClass> klasę.

Taikant metodą UseName() , deklaruojamas veiksmų išrinkiklio pavadinimas. Tai naudojama kaip veiksmo, skirto ištekliams išspręsti, pavadinimas.

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

Šiame konkrečiame pavyzdyje norime rodyti tik vieną iš argumentų, todėl kiti išfiltruojami. Panašiai ir su "Selector2":

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

Ir Selector3 klasės:

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

Galutinis vykdymas pasiekiamas naudojant Execute(ActionContext context) metodą, kuris yra pagrindiniame veiksme. Remiantis selektoriumi, rodomos atitinkamos filtruotos vertės.

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

Pasirinktiniai veiksmų parinkikliai, naudojantys Bulio logikos

Toliau pateikiamas pavyzdys, kuriame naudojami Bulio logikos, o ne išvardijimai.

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

Pasirinktinių veiksmų parinkiklių aprašų nustatymas

Norėdami sukurti aprašą ir suvestinę parinkikliams, pasirinktinio modulio .resx faile naudokite šį formatą.

SelectorName_Description
SelectorName_Summary

Tai taip pat galima padaryti selektoriuje naudojant metodus WithDescription ir WithSummary.

Pasirinktiniai modulio ID

Kiekvienas modulis turi savo ID (surinkimo pavadinimą). Kurdami pasirinktinius modulius įsitikinkite, kad nustatėte unikalius modulių ID. Norėdami nustatyti modulio surinkimo pavadinimą, modifikuokite ypatybę Surinkimo pavadinimas , esančią C# projekto ypatybių skyriuje Bendra.

Pasirinktinių modulių pavadinimų konvencijos

Kad pasirinktinius darbalaukio modulius būtų galima Power Automate perskaityti, AssemblyName turi turėti failo pavadinimą, kuris atitinka toliau pateiktą modelį:

?*.Modules.?*
Modules.?*

Pavyzdžiui,Moduliai . ContosoActions. DLL

AssemblyTitle projekto parametruose nurodo modulio ID. Jis gali turėti tik raidinius ir skaitmeninius simbolius bei pabraukimus ir turi prasidėti raide.

Pasirašykite visus DLL pasirinktiniame modulyje

Norėdami užbaigti pasirinktinio modulio kūrimą, visi sugeneruoti . DLL failai, kuriuos galima rasti projekto aplanke "bin/release" arba "bin/Debug", turi būti pasirašyti.

Pasirašykite visus . DLL failus naudodami patikimą sertifikatą programų kūrėjų komandinėje eilutėje vykdydami šią komandą (kiekvienam .DLL failui), skirtą Visual Studio:

Pasirašykite .dlls failus naudodami patikimą sertifikatą programų kūrėjų komandinėje eilutėje vykdydami šią komandą (kiekvienai DLL), skirtą 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

Arba vykdydami šią komandą (sukurdami "Windows PowerShell" scenarijų .ps1), kuri kartojasi per visus . DLL failus ir kiekvieną iš jų pasirašykite pateiktu sertifikatu:

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
}

Viską supakuokite į Kabinetinio formato failas

Šis . DLL, kuriame yra pasirinktiniai veiksmai ir visos jo priklausomybės (.DLL failai), turi būti supakuoti į Kabinetinio formato failas (.cab).

Sukurkite "Windows PowerShell" scenarijų (.ps1), kuriame yra šios eilutės:

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

Tada šį "Windows PowerShell" scenarijų galima naudoti kuriant .cab failą, iškviečiant jį "Windows PowerShell" ir pateikiant:

• Katalogas į . DLL failus, kuriuos reikia suglaudinti.
• Paskirties katalogas, skirtas sugeneruotam .cab failui įdėti.

Iškvieskite scenarijų naudodami šią sintaksę:

.\{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

Pavyzdys:

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

Paskesni veiksmai

Pasirinktinių veiksmų įkėlimas

Susijusi informacija

• Išteklių biblioteka
• Pasirinktinių veiksmų naudojimas
• Pasirinktiniai veiksmai