Stvaranje Power Automate akcija za radnu površinu pomoću SDK-a za akcije

Članak
08/05/2024

U ovom se članku opisuje kako stvoriti prilagođene akcije u aplikaciji Power Automate za stolna računala.

Izrada prilagođenih radnji

Važno

Rezervirane ključne riječi ne mogu se upotrebljavati kao nazivi radnji i/ili svojstva akcije. Korištenje rezerviranih ključnih riječi kao naziva radnji i/ili svojstava radnji rezultira pogrešnim ponašanjem. Dodatne informacije: Rezervirane ključne riječi u tijekovima radne površine

Započnite stvaranjem novog projekta biblioteke razreda (.NET Framework). Odaberite .NET Framework verzija 4.7.2.

Da biste formirali radnju u stvorenom prilagođenom modulu:

Izbrišite automatski generiranu Class1.cs datoteku.
Stvorite novu klasu unutar projekta koja će predstavljati prilagođenu radnju i dodijelite joj poseban naziv.
Uključite prostore naziva Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK i Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes.
Sve klase koje predstavljaju radnje trebaju imati atribut [Action] iznad vaše klase.
Klasa bi trebala imati javni pristup i nasljeđivati od klase 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();
        }
    }
}

Većina radnji ima parametre (ulaz ili izlaz). Ulazni i izlazni parametri predstavljeni su klasičnim C# svojstvima. Svako svojstvo treba imati odgovarajući atribut C#, ili [InputArgument] [OutputArgument] ili da diktira njegovu vrstu i način na koji su predstavljeni za Power Automate stolna računala. Ulazni argumenti također mogu imati zadane vrijednosti.

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

Dodavanje opisa prilagođenim akcijama

Dodajte opis i prijateljski naziv za module i radnje kako bi RPA programeri znali kako ih najbolje iskoristiti.

Power Automate Za Desktop Designer prikazuje prijateljske nazive i opise.

Možete stvoriti "Resources.resx" datoteku unutar mape Svojstva projekta modula. Nova datoteka ".resx" trebala bi se zvati "Resources.resx".

Format opisa modula i radnji trebao bi biti sljedeći:

"Module_Description" ili "Action_Description" i "Module_FriendlyName" ili "Action_FriendlyName" u polju imena. Opis u polju vrijednosti.

Također preporučujemo da navedete opise i prijateljske nazive za parametre. Njihov format trebao bi biti sljedeći: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Snimka zaslona resursa za jednostavnu radnju

Savjet

Preporučuje se da u polju za komentare označite što opisujete (npr. Modul, Akcija itd.)

Oni se također mogu postaviti sa svojstvima FriendlyName i Description atributa the,and [InputArgument] [OutputArgument] [Action] .

Evo primjera Resources.resx datoteke za prilagođeni modul.

Snimka zaslona resursa

Drugi način za brzo dodavanje prijateljskih naziva i opisa akcijama i parametrima je pomoću svojstava FriendlyName i Description u [Akcija] [InputArguement] i [OutputArguement] atributima.

Napomena

Da biste modulu dodali prijateljski naziv i opis, morate izmijeniti odgovarajuću .resx datoteku ili dodati odgovarajuće C# atribute.

Lokalizacija resursa

Pretpostavlja se da je zadani jezik za module za Power Automate stolna računala engleski.

Datoteka Resources.resx bi trebala biti na engleskom jeziku.

Bilo koji drugi jezici mogu se dodati s dodatnim resursima.{locale} Resx datoteke za lokalizaciju. Na primjer, Resources.fr.resx.

Prilagođene kategorije modula

Moduli mogu uključivati kategorije i potkategorije za bolju organizaciju djelovanja.

Da biste razdvojili prilagođene akcije u kategorije, potkategorije, izmijenite atribut [Action] koji prethodi klasi koja predstavlja prilagođenu radnju na sljedeći način:

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

Napomena

Modul može imati više kategorija. Slično tome, kategorije se mogu sastojati od potkategorija. Ova struktura može biti neograničena.

Svojstvo Order diktira redoslijed kojim se akcije pretpregledavaju u dizajneru.

Action1 spada u kategoriju "TestCategory" i to je prva radnja modula (na ovaj način objašnjavate Redoslijed i kategoriju na primjeru).

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

Uvjetne radnje

Uvjetne akcije su radnje koje vraćaju "True" ili "False". 'Ako datoteka postoji'za Power Automate radnu površinu radnja standardne biblioteke dobar je primjer uvjetne akcije.

Primjer uvjetne akcije:

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

Obratite pažnju na logičku varijablu Result .

Akcija Ako datoteka postoji nema izlazni argument. Ono što vraća je točno ili netočno, ovisno o tome što sadrži booleova varijabla Result .

Prilagođeni birači akcija

Postoje posebni slučajevi u kojima se može zahtijevati da prilagođena radnja ima više od jedne varijacije.

Primjer je radnja "Pokreni Excel" iz standardne biblioteke radnji.

Pomoću birača "s praznim dokumentom" tijek pokreće prazan Excel dokument, dok je pomoću odabira "i otvori sljedeći dokument" potreban put datoteke za otvaranje.

Snimka zaslona birača akcija Pokreni Excel

Dvije gore spomenute akcije dva su selektora osnovne akcije "Pokreni Excel".

Prilikom izrade prilagođenih radnji ne morate prepisivati funkcionalnost.

Možete stvoriti jednu "osnovnu" akciju, postavljajući njezine ulazne i izlazne parametre, a zatim odabrati što će biti vidljivo u svakom okusu pomoću selektora akcija.

Putem selektora akcija može se dodati razina apstrakcije preko jedne akcije, omogućujući dohvaćanje specifične funkcionalnosti iz jedne "osnovne" akcije bez potrebe za ponovnim pisanjem koda kako bi se svaki put formirala nova varijacija iste akcije.

Zamislite selektore kao izbore, filtrirajući jednu radnju i prikazujući samo potrebne informacije prema odgovarajućim biračima.

Snimka zaslona dijagrama selektora radnji

Da biste formirali novi birač akcija, prvo stvorite osnovnu akciju koju će koristiti birači.

Središnja akcija zahtijeva logičko svojstvo ili svojstvo enumeracija kao ulazni C# argument.

Vrijednost ovog svojstva određuje koji se birač koristi.

Najčešći način je korištenje enumeracija. Pogotovo kada su potrebna više od dva selektora, enums je jedina opcija.

Za dva slučaja selektora mogu se koristiti logički brojevi.

Ovo svojstvo, poznato i kao argument ograničenja, mora imati zadanu vrijednost.

Središnja radnja proglašena je klasičnom radnjom.

Primijetite da je prvo svojstvo (ulazni argument) enumeracija. Na temelju vrijednosti tog svojstva, odgovarajući birač postaje aktivan.

Napomena

Da bi argumenti bili poredani na željeni način, postavite vrijednost Order pokraj atributa 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
}

Prilagođeni birači akcija pomoću enuma

U ovom primjeru stvarate tri birača. Jednostavna enumeracija svaki put diktira odgovarajući birač:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Selektori su predstavljeni klasama.

Te klase moraju naslijediti klasu ActionSelector<TBaseActionClass> .

Napomena

TBaseActionClass je naziv osnovne akcijske klase.

U metodi UseName() deklarira se naziv birača akcije. To se koristi kao naziv akcije za rješavanje resursa.

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

Napomena

Klase Selector ne smiju se deklarirati kao akcije. Jedina radnja je središnja. Selektori djeluju kao filtri.

U ovom konkretnom primjeru želimo prikazati samo jedan od argumenata, tako da su ostali filtrirani. Slično za Selector2:

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

I Selector3 klase :

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

Konačno izvršenje postiže se metodom Execute(ActionContext context) koja se nalazi u središnjoj akciji. Na temelju birača prikazuju se odgovarajuće filtrirane vrijednosti.

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

Prilagođeni birači akcija pomoću logičke vrijednosti

Slijedi primjer korištenja Booleove vrijednosti umjesto enuma.

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

Postavljanje opisa za odabire prilagođenih radnji

Da biste stvorili opis i sažetak za selektore, upotrijebite sljedeći oblik u .resx datoteci prilagođenog modula.

SelectorName_Description
SelectorName_Summary

To se također može učiniti u biraču pomoću metoda WithDescription i WithSummary.

Važno

.dll datoteke koje opisuju prilagođene akcije, njihove .dll ovisnosti i .cab datoteka koja sadrži sve trebaju biti ispravno potpisane digitalnim certifikatom kojem vaša tvrtka ili ustanova vjeruje. Certifikat bi također trebao biti instaliran na svakom računalu na kojem je tijek radne površine s prilagođenim ovisnostima o akcijama autor/izmijenjen / izvršen, prisutan u pouzdanim korijenskim ustanovama za izdavanje certifikata.

Prilagođeni ID-ovi modula

Svaki modul ima svoj ID (naziv sklopa). Prilikom izrade prilagođenih modula provjerite jeste li postavili jedinstvene ID-ove modula. Da biste postavili naziv sklopa modula, izmijenite svojstvo Naziv sklopa u odjeljku Općenito svojstava C# projekta.

Upozorenje

Uključivanje modula s istim ID-om u tijek rezultirat će sukobima

Prilagođene konvencije naziva modula

Da bi prilagođeni moduli bili čitljivi Power Automate za radnu površinu, AssemblyName mora imati naziv datoteke koji slijedi obrazac u nastavku:

?*.Modules.?*
Modules.?*

Na primjer, Moduli. ContosoActions.dll

AssemblyTitle u postavkama projekta određuje ID modula. Može imati samo alfanumeričke znakove i podvlake i mora započeti slovom.

Potpišite sve DLL-ove unutar prilagođenog modula

Važno

Obavezno je imati sve .dll datoteke koje čine prilagođeni modul (generirani sklop i sve njegove ovisnosti) potpisane pouzdanim certifikatom

Da biste dovršili izradu prilagođenog modula, moraju biti potpisane sve generirane .dll datoteke, koje se mogu pronaći u mapi bin/release ili bin/Debug projekta.

Potpišite sve .dll datoteke pomoću pouzdanog certifikata pokretanjem sljedeće naredbe (za svaku .dll datoteku) u naredbenom retku razvojnog inženjera za Visual Studio:

Potpišite .dlls datoteke pomoću pouzdanog certifikata pokretanjem sljedeće naredbe (za svaki dll) u naredbenom retku razvojnog inženjera za 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

Ili pokretanjem sljedeće naredbe (stvaranjem skripte komponente Windows PowerShell .ps1) koja ponavlja sve .dll datoteke i svaku od njih potpiše priloženim certifikatom:

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
}

Napomena

Digitalni certifikat mora imati privatni ključ koji se može izvesti i mogućnosti potpisivanja koda

Pakiranje svega u datoteku ormarića

.dll koji sadrži prilagođene radnje i sve njegove ovisnosti (.dll datoteke) mora biti upakiran u datoteku kabineta (.cab).

Napomena

Prilikom imenovanja .cab datoteke slijedite konvenciju imenovanja datoteka i mapa za operacijski sustav Windows. Nemojte koristiti prazne razmake ili posebne znakove kao što su < > : " / \ | ? * .

Stvorite skriptu komponente Windows PowerShell (.ps1) koja sadrži sljedeće retke:

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

Ova Windows PowerShell skripta se zatim može koristiti za stvaranje .cab datoteke pozivanjem u Windows PowerShell i pružanjem:

Direktorij za .dll datoteka koje treba komprimirati.
Ciljni direktorij za postavljanje generirane .cab datoteke.

Pozovite skriptu pomoću sljedeće sintakse:

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

Primjer:

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

Napomena

Provjerite jesu li stvarne prilagođene akcije .dll datoteku na korijenskoj razini ciljanog puta prilikom stvaranja .cab datoteke, a ne u podmapi.
Datoteka .cab također mora biti potpisana. Nepotpisane .cab datoteke i/ili nepotpisani .dll-ovi sadržani u njima neće biti upotrebljivi u tijekovima radne površine i rezultirat će pogreškom tijekom uključivanja.

Sljedeći koraci

Prijenos prilagođenih radnji

Dijeli putem

Stvaranje Power Automate akcija za radnu površinu pomoću SDK-a za akcije

Izrada prilagođenih radnji

Dodavanje opisa prilagođenim akcijama

Lokalizacija resursa

Prilagođene kategorije modula

Uvjetne radnje

Prilagođeni birači akcija

Prilagođeni birači akcija pomoću enuma

Prilagođeni birači akcija pomoću logičke vrijednosti

Postavljanje opisa za odabire prilagođenih radnji

Prilagođeni ID-ovi modula

Prilagođene konvencije naziva modula

Potpišite sve DLL-ove unutar prilagođenog modula

Pakiranje svega u datoteku ormarića

Sljedeći koraci

Povratne informacije

Dodatni resursi

Dijeli putem

Stvaranje Power Automate akcija za radnu površinu pomoću SDK-a za akcije

Izrada prilagođenih radnji

Dodavanje opisa prilagođenim akcijama

Lokalizacija resursa

Prilagođene kategorije modula

Uvjetne radnje

Prilagođeni birači akcija

Prilagođeni birači akcija pomoću enuma

Prilagođeni birači akcija pomoću logičke vrijednosti

Postavljanje opisa za odabire prilagođenih radnji

Prilagođeni ID-ovi modula

Prilagođene konvencije naziva modula

Potpišite sve DLL-ove unutar prilagođenog modula

Pakiranje svega u datoteku ormarića

Sljedeći koraci

Povezane informacije

Povratne informacije

Dodatni resursi