Darbvirsmas darbību izveide Power Automate , izmantojot darbību SDK

Šajā rakstā ir aprakstīts, kā izveidot pielāgotas darbības Power Automate darbvirsmai.

Pielāgotu darbību izveide

Sāciet ar jauna klases bibliotēkas (.NET Framework) projekta izveidi. Atlasiet .NET Framework versiju 4.7.2.

Lai izveidotu darbību izveidotajā pielāgotajā modulī:

• Izdzēsiet automātiski ģenerēto Class1.cs failu.
• Izveidojiet jaunu mācību priekšmetu savā projektā, lai attēlotu pielāgoto darbību, piešķirot tai atšķirīgu nosaukumu.
• Iekļaujiet Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK un Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes nosaukumvietas.
• Visām klasēm, kas attēlo darbības, virs jūsu klases ir jābūt atribūtam [Darbība].
• Klasei jābūt publiski pieejamai un mantotai no ActionBase klases.

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

Lielākajai daļai darbību ir parametri (ievade vai izvade). Ievades un izvades parametrus attēlo klasiskie C# rekvizīti. Katram rekvizītam ir jābūt atbilstošam C# atribūtam, vai nu [InputArgument] , lai [OutputArgument] diktētu tā veidu un to, kā tas tiek attēlots Power Automate darbvirsmai. Ievades argumentiem var būt arī noklusējuma vērtības.

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

Aprakstu pievienošana pielāgotām darbībām

Pievienojiet moduļu un darbību aprakstu un draudzīgu nosaukumu, lai RPA izstrādātāji zinātu, kā tos vislabāk izmantot.

Power Automate Darbvirsmas noformētājam tiek rādīti draudzīgi nosaukumi un apraksti.

Jūs varat izveidot "Resources.resx" failu moduļa projekta mapē Properties. Jaunajam ".resx" failam jābūt ar nosaukumu "Resources.resx".

Moduļu un darbību aprakstu formātam jābūt šādam:

"Module_Description" vai "Action_Description" un "Module_FriendlyName" vai "Action_FriendlyName" attiecīgi nosaukuma laukā. Apraksts vērtības laukā.

Mēs arī iesakām sniegt aprakstus un draudzīgus parametru nosaukumus. To formātam jābūt šādam: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Tos var iestatīt arī ar rekvizītiem FriendlyName un Description, [InputArgument]un [OutputArgument] [Action] atribūtiem.

Tālāk ir sniegts pielāgota moduļa faila piemērs Resources.resx .

Vēl viens veids, kā darbībām un parametriem ātri pievienot draudzīgus nosaukumus un aprakstus, ir rekvizīti FriendlyName un Description sadaļā [Darbība] [InputArguement] un [OutputArguement] atribūti.

Kļūdu apstrādes pievienošana pielāgotām darbībām

Lai savā darbībā definētu pielāgotus izņēmumus, izmantojiet [Throws("ActionError")] atribūtu virs pielāgotās darbību klases. Katram izņēmuma gadījumam, ko vēlaties definēt, ir jābūt savam atribūtam.

Nozvejas blokā izmantojiet šādu kodu:

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

Pārliecinieties, ActionException vai nosaukums atbilst atribūtā Throws norādītajam vārdam. Izmantojiet throw new ActionException katram izņēmuma gadījumam un saskaņojiet to ar atbilstošo Throws atribūta nosaukumu. Visi izņēmumi, kas definēti ar atribūtu, Throws ir redzami noformētāja darbības kļūdu apstrādes cilnē.

Piemērs tam ir atrodams sadaļā Nosacītās darbības .

Resursu lokalizācija

Tiek pieņemts, ka darbvirsmas moduļu Power Automate noklusējuma valoda ir angļu valoda.

Failam Resources.resx jābūt angļu valodā.

Jebkuras citas valodas var pievienot, izmantojot papildu resursus.{locale}. resx faili lokalizācijai. Piemēram, Resources.fr.resx.

Pielāgotas moduļu kategorijas

Moduļos var iekļaut kategorijas un apakškategorijas labākai darbības organizācijai.

Lai atdalītu pielāgotas darbības kategorijās, apakškategorijās, modificējiet atribūtu [Darbība], kas atrodas pirms klases, kura attēlo pielāgoto darbību, šādā veidā:

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

Pasūtījuma rekvizīts nosaka secību, kādā noformētājā tiek priekšskatītas darbības.

Action1 pieder kategorijai "TestCategory" un tā ir moduļa pirmā darbība (tādā veidā jūs izskaidrojat secību un kategoriju ar piemēru).

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

Nosacītas darbības

Nosacītās darbības ir darbības, kas atgriež vai nu "True", vai "False". "Ja fails pastāv" Power Automate standarta bibliotēkas darbvirsmas darbībai ir labs nosacītas darbības piemērs.

Nosacījuma darbības piemērs:

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

Ievērojiet rezultātu Būla mainīgo.

Darbībai Ja fails pastāv , nav izvades argumenta. Tas, ko tas atgriež, ir patiess vai aplams atkarībā no tā, kāds ir Būla mainīgais rezultāts .

Pielāgoti darbību atlasītāji

Ir īpaši gadījumi, kad pielāgotai darbībai var būt nepieciešams vairāk nekā viens variants.

Piemērs ir darbība "Launch Excel" no standarta darbību bibliotēkas.

Izmantojot atlasītāju "ar tukšu dokumentu", plūsma palaiž tukšu Excel dokumentu, savukārt, izmantojot atlasi "un atveriet nākamo dokumentu", ir jāatver faila ceļš.

Divas iepriekš minētās darbības ir divi bāzes darbības "Launch Excel" atlasītāji.

Veidojot pielāgotas darbības, funkcionalitāte nav jāpārraksta.

Izmantojot darbību atlasītājus, varat izveidot vienu "bāzes" darbību, iestatot tās ievades un izvades parametrus, un pēc tam izvēlēties, kas būtu redzams katrā garšā.

Izmantojot darbību atlasītājus, abstrakcijas līmeni var pievienot vienai darbībai, ļaujot izgūt specifisku funkcionalitāti no vienas "bāzes" darbības bez nepieciešamības pārrakstīt kodu, lai katru reizi izveidotu jaunu tās pašas darbības variantu.

Padomājiet par selektoriem kā izvēli, filtrējot vienu darbību un parādot tikai to informāciju, kas nepieciešama saskaņā ar attiecīgajiem atlasītājiem.

Lai izveidotu jaunu darbību atlasītāju, vispirms izveidojiet bāzes darbību, ko izmantos atlasītāji.

Centrālajai darbībai ir nepieciešams Būla vai uzskaitījums rekvizīts kā ievades C# arguments.

Šī īpašuma vērtība nosaka, kurš selektors tiek izmantots.

Visizplatītākais veids ir uzskaitījums izmantošana. It īpaši, ja ir nepieciešami vairāk nekā divi selektori, enums ir vienīgā iespēja.

Diviem selektoru korpusiem var izmantot būla paraugus.

Šim rekvizītam, kas tiek dēvēts arī par ierobežojuma argumentu, ir jābūt noklusējuma vērtībai.

Centrālā darbība tiek pasludināta par klasisku darbību.

Ievērojiet, ka pirmais rekvizīts (ievades arguments) ir uzskaitījums. Pamatojoties uz šī īpašuma vērtību, atbilstošais atlasītājs kļūst aktīvs.

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
}

Pielāgoti darbību atlasītāji, izmantojot enums

Šajā piemērā jūs izveidojat trīs atlasītājus. Vienkāršs uzskaitījums katru reizi diktē atbilstošo selektoru:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Selektorus pārstāv klases.

Šīm klasēm ir jāpārmanto ActionSelector<TBaseActionClass> klase.

Metodē UseName() tiek deklarēts darbību atlasītāja nosaukums. Tas tiek izmantots kā darbības nosaukums, lai atrisinātu resursus.

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

Šajā konkrētajā piemērā mēs vēlamies parādīt tikai vienu no argumentiem, tādējādi pārējie tiek filtrēti. Līdzīgi kā Selector2:

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

Un Selector3 klases:

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

Galīgā izpilde tiek panākta, izmantojot Izpildes (ActionContext konteksta) metodi, kas atrodas centrālajā darbībā. Pamatojoties uz atlasītāju, tiek parādītas attiecīgās filtrētās vērtības.

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

Pielāgoti darbību atlasītāji, izmantojot Būla

Šis ir piemērs, kurā enums tiek izmantots Būla, nevis 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);
        }
    }
}

Pielāgotu darbību atlasītāju aprakstu iestatīšana

Lai atlasītājiem izveidotu aprakstu un kopsavilkumu, pielāgotā moduļa .resx failā izmantojiet šādu formātu.

SelectorName_Description
SelectorName_Summary

To var izdarīt arī atlasītājā, izmantojot metodes WithDescription un WithSummary.

Pielāgoti moduļa ID

Katram modulim ir savs ID (montāžas nosaukums). Veidojot pielāgotus moduļus, pārliecinieties, vai iestatāt unikālus moduļu ID. Lai iestatītu moduļa montāžas nosaukumu, modificējiet rekvizītu Asamblejas nosaukums , kas atrodas C# projekta rekvizītu sadaļā Vispārīgi.

Pielāgotas moduļa nosaukumu konvencijas

Lai pielāgotos moduļus varētu lasīt Power Automate darbvirsmai, AssemblyName ir jābūt faila nosaukumam, kas atbilst tālāk norādītajam modelim.

?*.Modules.?*
Modules.?*

Piemēram, Moduļi. ContosoActions. DLL

Projekta iestatījumos AssemblyTitle norāda moduļa ID. Tam var būt tikai burtciparu rakstzīmes un pasvītrojumi, un tam jāsākas ar burtu.

Parakstiet visus DLL pielāgotajā modulī

Lai pabeigtu pielāgotā moduļa izveidi, visi ģenerēti . DLL faili, kas atrodami projekta bin/release vai bin/Debug mapē, ir jāparaksta.

Parakstiet visu . DLL failus, izmantojot uzticamu sertifikātu, izstrādātāja komandu uzvednē palaižot šādu komandu (katram .DLL failam Visual Studio):

Parakstiet .dlls failus, izmantojot uzticamu sertifikātu, izstrādātāja komandu uzvednē Visual Studio palaižot tālāk norādīto komandu (katrai DLL):

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

Vai palaižot tālāk norādīto komandu (izveidojot Windows PowerShell skriptu .ps1), kas atkārtojas cauri visiem . DLL failus un parakstiet katru ar sniegto sertifikātu:

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
}

Visu iepakošana kabinetfails

2019. gada 1 DLL, kurā ir ietvertas pielāgotās darbības un visas to atkarības (.DLL faili), ir jāiepako kabinetfails (.cab).

Izveidojiet Windows PowerShell skriptu (.ps1), kurā ir šādas rindas:

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

Šo Windows PowerShell skriptu pēc tam var izmantot, lai izveidotu .cab failu, izsaucot to programmā Windows PowerShell un nodrošinot:

• Direktorija uz . DLL saspiežamos failus.
• Mērķa direktorijs, lai ievietotu ģenerēto .cab failu.

Izsauciet skriptu, izmantojot šādu sintaksi:

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

Piemērs:

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

Nākamās darbības

Pielāgotu darbību augšupielāde

Saistītā informācija

• Līdzekļu bibliotēka
• Pielāgotu darbību izmantošana
• Pielāgotas darbības