Jaa


Power Automate -työpöytäsovelluksen toimintojen luominen Actions SDK:n avulla

Tässä artikkelissa kuvataan, kuinka voit luoda mukautettuja toimintoja Power Automate -työpöydälle.

Mukautettujen toimintojen luominen

Tärkeää

Varattuja avainsanoja ei voi käyttää toimintojen niminä ja/tai toiminto-ominaisuuksina. Varattujen avainsanojen käyttö toimintojen niminä ja/tai toiminto-ominaisuuksina johtaa virheelliseen toimintaan. Lisätietoja: Varatut avainsanat työpöytätyönkuluissa

Aluksi luodaan uusi luokkakirjastoprojekti (.NET Framework). Valitse .NET framework -versio 4.7.2.

Toiminnon muodostaminen luodussa mukautetussa moduulissa:

  • Poista automaattisesti luotu Class1.cs-tiedosto.
  • Luo projektiin uusi luokka ilmaisemaan mukautettua toimintoa ja anna sille erottuva nimi.
  • Sisällytä Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK- ja Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes-nimitilat.
  • Kaikilla toimintoja ilmaisevilla luokilla on oltava [Toiminto]-määrite luokan yläpuolella.
  • Luokalla on oltava julkinen käyttöoikeus ja sen perittävä ActionBase-luokasta.
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();
        }
    }
}

Useimmilla toiminnoilla on parametreja (syöte tai tulos). Syöte- ja tulosparametrit ilmaistaan perinteisinä C#-ominaisuuksina. Kullakin ominaisuudessa on oltava soveltuva C#-määrite, joko [InputArgument] tai [OutputArgument], joka määrää sen tyypin ja esittämistavan Power Automate -työpöytäsovelluksessa. Syöteargumentilla voi olla myös oletusarvoja.

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

Kuvausten lisääminen mukautettuihin toimintoihin

Moduulien ja toimintojen kuvauksen ja kutsumanimen lisääminen auttaa RPA-kehittäjiä hyödyntämään niitä tehokkaasti.

Kutsumanimet ja kuvaukset näkyvät Power Automate -työpöytäsovelluksessa.

Resources.resx-tiedosto voidaan luodaan moduuliprojektin Ominaisuudet-kansiossa. Uuden .resx-tiedoston nimen on oltava Resources.resx.

Moduulien ja toimintojen kuvausten muoto on seuraava:

Moduulin_kuvaus tai Toiminnon_kuvaus ja nimikentässä vastaavasti Moduulin_kutsumanimi tai Toiminnon_kutsumanimi. Kuvaus on arvokentässä.

Suosittelemme myös, että annat parametreille kuvaukset ja ystävälliset nimet. Niiden muoto on seuraava: Toiminnon_parametrin_kuvaus ja Toiminnon_parametrin_kutsumanimi.

Näyttökuvassa yksinkertaisen toiminnon resurssit

Vihje

Kommentti kenttään kannattaa lisätä, mitä ollaan kuvailemassa (kuten Moduuli tai Toiminto).

Nämä voidaan määrittää myös [InputArgument]-, [OutputArgument]- ja [Action]-määritteiden FriendlyName- ja Description-ominaisuuksien avulla:

Esimerkki mukautetun moduulin Resources.resx-tiedostosta.

Näyttökuvassa resurssit

Toimintojen ja parametrien kutsumanimet ja kuvaukset voi lisätä nopeasti myös käyttämällä FriendlyName- ja Description-ominaisuuksia [Toiminto]-, [InputArguement]- ja [OutputArguement]-määritteissä.

Huomautus

Jos haluat lisätä moduulille käyttäjäystävällisen nimen ja kuvauksen, sinun täytyy muokata vastaavaa .resx-tiedostoa tai lisätä vastaavat C#-määritteet.

Virheenkäsittelyn lisääminen mukautettuihin toimintoihin

Voit määrittää toiminnolle mukautettuja poikkeuksia käyttämällä [Throws("ActionError")]-määritettä mukautetun toimintoluokan yläpuolella. Jokaisella määritettävällä poikkeustapauksella on oltava oma määritteensä.

Käytä catch-lohkossa seuraavaa koodia:

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

Varmista, että ActionException-nimi vastaa määritteessä Throws antamaasi nimeä. Käytä throw new ActionException-toimintoa kunkin poikkeustapauksen osalta ja yhdistä se vastaavaan Throws-määritteen nimeen. Kaikki määritteellä Throws määritetyt poikkeukset näkyvät suunnitteluohjelman toimintovirheiden käsittelyn välilehdessä.

Esimerkki tästä esitetään Ehdolliset toiminnot -osassa.

Resurssien lokalisointi

Power Automate -työpöytäsovelluksen moduulien oletuskielen oletetaan olevan englanti.

Resources.resx-tiedoston on oltava englanninkielinen.

Lokalisointia varten voidaan lisätä muita kieliä käyttämällä ylimääräisiä Resources.{locale}.resx-tiedostoja. Esimerkki: Resources.fr.resx.

Mukautetun moduulin luokat

Moduulit voivat sisältää luokkia ja alaluokkia, mikä parantaa toiminnon järjestelyä.

Mukautetut toiminnot voidaan eritellä luokkiin ja alaluokkiin muokkaamalla sitä luokkaa edeltävää [Toiminto]-määritettä, joka ilmaisee mukautetun toiminnon. Tämä tehdään seuraavasti:

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

Huomautus

Moduulissa voi olla useita luokkia. Vastaavasti luokat voivat koostua alaluokista. Tämä rakenne voi olla rajoittamaton.

Järjestys-ominaisuus määrää järjestyksen, jossa toimintoja esikatsellaan suunnitteluohjelmassa.

Action1 kuuluu luokkaan "TestCategory" ja se on moduulin ensimmäinen toiminto (tällä tavoin voit selittää järjestyksen ja luokan käyttämällä esimerkkiä).

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

Ehdolliset toiminnot

Ehdolliset toiminnot ovat toimintoja, jotka palauttavat tulokseksi joko Tosi tai Epätosi. Power Automate -työpöytäsovelluksen vakiokirjaston toiminto Jos tiedosto on olemassa on hyvä esimerkki ehdollisesti toiminnosta.

Esimerkki ehdollisesta toiminnosta:

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

Kiinnitä huomiota tuloksen totuusarvomuuttujaan.

Jos tiedosto on olemassa -toiminnolla ei ole tulosargumenttia. Niinpä sen tuloksena onkin joko tosi tai epätosi sen mukaan, mikä totuusarvomuuttuja tuloksella on.

Mukautetut toiminnon valitsimet

Tietyissä tapauksissa mukautetulla toiminnolla on oltava useampi kuin yksi variaatio.

Tässä esimerkki on toimintojen vakiokirjaston Käynnistä Excel -toiminto.

Kun sen kanssa on käytössä tyhjän tiedoston kanssa -valitsin, työnkulku käynnistää tyhjän Excel-tiedoston, kun taas ja avaa seuraava tiedosto -valinta edellyttää, että tiedoston tiedostopolku avataan.

Näyttökuvassa Käynnistä Excel -toiminnon valitsimet

Edellä mainitut kaksi toimintoa ovat kaksi Käynnistä Excel -perustoiminnon valitsinta.

Mukautettuja toimintoja luotaessa toimintoa ei tarvitse kirjoittaa uudelleen:

Sen sijaan voidaan luoda yksi perustoimintoa, jolle määritetään syöte- ja tulosparametrit sekä valitaan, mikä on kulloinkin näkyvissä toimintovalitsimia hyödyntämällä.

Toimintovalitsimien avulla yhteen toimintoon voi lisätä abstraktiotaso, mikä mahdollistaa tietyn toiminnon noutamisen yhdestä perustoiminnosta ilman, että olisi joka kerta kirjoitettava uudelleen saman toiminnon uuden variaation muodostava koodi.

Valitsimet ovatkin ikään kuin valintoja, jotka suodattavat yhden toiminnon ja näyttävät vain kyseisten valitsimien mukaiset tiedot.

Näyttökuvassa toiminnon valitsinkaavio

Uusi toimintovalitsin muodostetaan luomalla ensin valitsimien käyttämä perustoiminto.

Keskustoiminto tarvitsee joko totuusarvo- tai luettelointiominaisuuden syötteen C#-argumentiksi.

Tämän ominaisuuden arvo määrittää käytettävän valitsimen.

Yleisin tapa on käyttää luettelointia. Luettelointi on myös ainoa vaihtoehto, jos valitsimia tarvitaan enemmän kuin kaksi.

Jos valitsimia on kaksi, totuusarvon käyttäminen on mahdollista.

Tällä ominaisuudella, jota kutsutaan myös rajoitusargumentiksi, on oltava oletusarvo.

Keskustoiminto ilmaistaan perinteisenä toimintona.

On huomattava, että ensimmäinen ominaisuus (syöteargumentti) on luettelointi. Soveltuva valitsin aktivoituu ominaisuuden arvon perusteella.

Huomautus

Argumentit järjestetään sopivaan järjestykseen määrittämällä järjestysarvo InputArgument-määritteen vieressä.

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
}

Luettelointia käyttävät mukautetun toiminnon valitsimet

Tässä esimerkissä luodaan kolme valitsinta. Yksinkertainen luettelointi määrää soveltuvan valitsimen kullakin kerralla:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Valitsimet ilmaistaan luokkina.

Näiden luokkien on perittävä ActionSelector<TBaseActionClass>-luokka.

Huomautus

TBaseActionClass on perustoiminnon luokan nimi.

Toimintovalitsimen luokan nimi ilmoitetaan UseName()-menetelmässä. Tätä käytetään toiminnon nimenä resursseja ratkaistaessa.

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

Huomautus

Valitsin-luokkia ei saa ilmoittaa toimintoina. Keskustoiminto on ainoa toiminto. Valitsimet toimivat suodattimina.

Tässä kyseisessä esimerkissä halutaan näyttää vain yksi argumentti, joten muut suodatetaan poista. Vastaavasti Selector2-luokissa:

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

Ja Selector3-luokissa:

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

Lopullinen suoritus tehdään keskustoiminnossa sijaitsevalla Execute(ActionContext context)-menetelmällä. Valitsimen perusteella suodatetut arvo näytetään.

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

Totuusarvo käyttävät mukautetun toiminnon valitsimet

Seuraavassa esimerkissä käytetään totuusarvoa luetteloinnin sijaan.

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

Mukautetun toiminnon valitsimien kuvausten määrittäminen

Valitsimien kuvaus ja yhteenveto luodaan käyttämällä seuraavaa muotoa mukautetun moduulin .resx-tiedostossa.

SelectorName_Description
SelectorName_Summary

Se voidaan tehdä myös valitsimessa WithDescription- ja WithSummary-menetelmien avulla.

Tärkeää

Mukautettuja toimintoja kuvaavat .dll-tiedostot, niiden .dll-riippuvuudet ja kaiken tämän sisältävä .cab-tiedosto on allekirjoitettava oikein digitaalisella varmenteella, johon organisaatio luottaa. Varmenne olisi asennettava myös kaikille koneille, joissa mukautettuja toimintoriippuvuuksia sisältävää työpöytätyönkulkua luodaan/muokataan/suoritetaan ja jotka ovat luotettujen varmenteiden päämyöntäjien alla.

Mukautetut moduulitunnukset

Jokaisella moduulilla on oma tunnuksensa (kokoonpanonimi). Mukautettuja moduuleja luotaessa on muistettava määrittää yksilöivät moduulitunnukset. Voit määrittää moduulisi kokoonpanonimen muokkaamalla Kokoonpanon nimi -ominaisuutta C#-projektin ominaisuuksien Yleiset-osasta.

Varoitus

Saman tunnuksen sisältävien moduulien sisällyttäminen työnkulkuun aiheuttaa ristiriitoja

Mukautetun moduuli nimikäytännöt

Mukautettujen moduulien luettavuus koko Power Automate -työpöytäsovelluksessa edellyttää, että AssemblyName-nimen tiedostonimen on oltava seuraavan mallin mukainen:

?*.Modules.?*
Modules.?*

Esimerkki: Modules.ContosoActions.dll

Projektiasetusten AssemblyTitle määrittää moduulin tunnuksen. Siinä saa käyttää vain aakkosnumeerisia merkkejä ja alaviivoja, minkä lisäksi ensimmäisen merkin on oltava kirjain.

Kaikkien mukautetun moduulin sisällä olevien DLL-tiedostojen allekirjoittaminen

Tärkeää

Kaikki .dll-tiedostot, joista mukautettu moduuli koostuu (luotu kokoonpano ja kaikki sen riippuvuudet), täytyy allekirjoittaa luotetulla varmenteella

Mukautetun moduulin luonnin viimeistely edellyttää, että kaikki luodut .dll-tiedostot, jotka löytyvät projektin bin/release- tai bin/Debug-kansiosta, on allekirjoitettu.

Allekirjoita kaikki .dll-tiedostot luotetulla varmenteella suorittamalla Developer Command Prompt for Visual Studiossa seuraava komento (jokaiselle .dll-tiedostolle):

Allekirjoita .dll-tiedostot luotetulla varmenteella suorittamalla Developer Command Prompt for Visual Studiossa seuraava komento (jokaiselle .dll-tiedostolle):

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

Tai suorittamalla seuraava komento (luomalla Windows PowerShell Script .ps1), joka iteroi kaikkiin .dll-tiedostoihin, ja allekirjoita jokainen niistä mukana toimitettavalla varmenteella:

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
}

Muistiinpano

Digitaalisessa varmenteessa on oltava vietävä yksityinen avain ja koodin allekirjoitusominaisuudet

Koko sisällön pakkaaminen .cab-tiedostoon

Mukautetut toiminnot ja sen riippuvuudet sisältävä .dll-tiedosto (.dll-tiedostot) täytyy pakata .cab-tiedostoon (.cab).

Huomautus

.cab-tiedostoa nimettäessä on noudatettava Windows-käyttöjärjestelmän tiedostojen ja kansioiden nimeämiskäytäntöä. Nimessä ei saa käyttää tyhjiä merkkejä eikä erikoismerkkejä, kuten < > : " / \ | ? * .

Luo seuraavat rivit sisältävä Windows PowerShell -komentosarja (.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

Tämän Windows PowerShell -komentosarjan avulla voidaan sitten luoda .cab-tiedosto käynnistämällä se Windows PowerShellissä ja antamalla seuraavat:

  • Hakemisto, johon .dll-tiedostot pakataan.
  • Kohdehakemisto, johon luotu .cab-tiedosto sijoitetaan.

Käynnistä komentosarja käyttämällä seuraavaa syntaksia:

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

Esimerkki:

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

Muistiinpano

  • Varmista, että kulloinenkin mukautettujen toimintojen .dll-tiedosto on kohteena olevan polun päätasolla eikä alikansiossa, kun luot .cab-tiedoston.
  • Myös .cab-tiedosto on allekirjoitettava. Jos .cab-tiedostoja ja/tai niissä olevia .dll-tiedostoja ei ole allekirjoitettu, niitä ei voi käyttää työpöytätyönkuluissa, ja ne aiheuttavat käytettäessä virheen.

Seuraavat vaiheet

Lataa mukautetut toiminnot