Sdílet prostřednictvím

Vytvoření Power Automate pro desktopové akce pomocí sady Actions SDK

  • Článek

Tento článek popisuje, jak vytvořit vlastní akce v Power Automate pro desktop.

Vytvoření vlastních akcí

Důležité

Vyhrazená klíčová slova nelze použít jako názvy akcí ani vlastnosti akce. Použití vyhrazených klíčových slov jako názvů akcí nebo vlastností akcí má za následek chybné chování. Další informace: Vyhrazená klíčová slova v desktopových tocích

Začněte vytvořením nového projektu knihovny tříd (.NET Framework). Vyberte .NET Framework verze 4.7.2.

Chcete-li vytvořit akci ve vytvořeném vlastním modulu:

  • Odstraňte automaticky vygenerovaný soubor Class1.cs.
  • Vytvořte v projektu novou třídu, která bude reprezentovat vlastní akci a dejte jí odlišný název.
  • Zahrňte obory názvů Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK a Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes.
  • Všechny třídy představující akce by měly mít nad vaší třídou atribut [Action].
  • Třída by měla mít veřejný přístup a dědit z třídy 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();
        }
    }
}

Většina akcí má parametry (vstupní nebo výstupní). Vstupní a výstupní parametry jsou reprezentovány klasickými vlastnostmi C#. Každá vlastnost by měla mít příslušný atribut buď C#, [InputArgument] nebo [OutputArgument] k diktování jejího typu a způsobu prezentace v Power Automate pro desktopy. Vstupní argumenty mohou mít také výchozí hodnoty.

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

Přidání popisů k vlastním akcím

Přidejte popis a popisný název pro moduly a akce, aby vývojáři RPA věděli, jak je nejlépe využít.

Návrhář aplikace Power Automate pro desktopy zobrazuje popisné názvy a popisy.

Můžete vytvořit soubor „Resources.resx“ ve složce Properties projektu modulu. Nový soubor ".resx" by se měl jmenovat „Resources.resx“.

Formát popisů modulů a akcí by měl být následující:

„Popis_modulu“ nebo „Popis_akce“ a „Popisný_název_modulu“ nebo „Popisný_název_akce“ v poli názvu. Popis v poli s hodnotou.

Doporučujeme také uvést popisy a popisné názvy parametrů. Jejich formát by měl být následující: „Popis_parametru_akce“, „Popisný_název_parametru_akce“.

Screenshot obrazovky Zdroje pro jednoduchou akci

Tip

Doporučujeme do pole komentáře uvést, co popisujete (např. Modul, Akce atd.)

Ty lze také nastavit pomocí vlastností FriendlyName a Description atributů [InputArgument], [OutputArgument] a [Action].

Zde je příklad souboru Resources.resx pro vlastní modul.

Screenshot zdrojů

Dalším způsobem, jak rychle přidat popisné názvy a popisy k akcím a parametrům, je pomocí vlastností FriendlyName a Description v atributech [Action], [InputArguement] a [OutputArguement].

Poznámka:

Chcete-li k modulu přidat popisný název a popis, musíte upravit příslušný soubor .resx nebo přidat příslušné atributy C#.

Přidání zpracování chyb k vlastním akcím

Chcete-li v akci definovat vlastní výjimky, použijte atribut [Throws("ActionError")] nad třídou vlastní akce. Každý případ výjimky, který chcete definovat, musí mít svůj vlastní atribut.

V catch bloku použijte následující kód:

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

Ujistěte se, že název ActionException odpovídá názvu, který jste zadali v atributu Throws. Použijte throw new ActionException pro každý případ výjimky a spárujte ho s odpovídajícím názvem atributu Throws. Všechny výjimky definované pomocí atributu Throws jsou viditelné na kartě zpracování chyb akcí návrháře.

Příklad najdete v části Podmíněné akce.

Lokalizace zdrojů

Výchozí jazyk modulů v Power Automate pro desktopy je angličtina.

Soubor Resources.resx by měl být v angličtině.

Jakékoli další jazyky lze přidat pomocí dodatečných souborů Resources.{locale}.resx pro lokalizaci. Například Resources.fr.resx.

Kategorie vlastních modulů

Moduly mohou obsahovat kategorie a podkategorie pro lepší organizaci akcí.

Chcete-li rozdělit vlastní akce do kategorií a podkategorií, upravte atribut [Action], který předchází třídě představující vlastní akci, následujícím způsobem:

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

Poznámka:

Modul může mít více kategorií. Podobně lze kategorie rozdělit do podkategorií. Tato struktura může být neurčitá.

Vlastnost Order určuje pořadí, ve kterém jsou akce v návrháři zobrazeny.

Action1 patří do kategorie „TestCategory“ a je to první akce modulu (tímto způsobem vysvětlíte objednávku a kategorii na příkladu).

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

Podmíněné akce

Podmíněné akce jsou akce, které vrací buď „pravda“ nebo „nepravda“. Akce „Když soubor existuje“ aplikace Power Automate pro desktopy ve standardní knihovně je dobrým příkladem podmíněné akce.

Příklad podmíněné akce:

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

Všimněte si logické proměnné Výsledek (Result).

Akce Když soubor existuje (If file exists) nemá výstupní argument. Vrací buď pravdu nebo nepravdu v závislosti na tom, co obsahuje logická proměnná Výsledek.

Selektory vlastní akce

V některých případech může být potřeba, aby vlastní akce měla více než jednu variantu.

Příkladem je akce „Spustit Excel“ (Launch Excel) ze standardní knihovny akcí.

Pomocí selektoru „s prázdným dokumentem“ (with a blank document) spustí tok prázdný dokument Excel, zatímco použití výběru „a otevřít následující dokument“ (and open the following document) vyžaduje cestu k souboru, aby byl otevřen.

Screenshot selektorů akce Spustit Excel

Dvě výše uvedené akce jsou dva selektory základní akce „Spustit Excel“.

Při vytváření vlastních akcí nemusíte přepisovat funkčnost.

Můžete vytvořit jednu „základní“ akci, nastavit její vstupní a výstupní parametry a poté pomocí selektorů akcí zvolit, co bude v každé variantě viditelné.

Prostřednictvím selektorů akce lze přes jednu akci přidat úroveň abstrakce, což umožňuje získat konkrétní funkčnost z jediné „základní“ akce, aniž by bylo nutné přepisovat kód, aby se pokaždé vytvořila nová variace stejné akce.

Přemýšlejte o selektorech jako o možnostech, které filtrují jednu akci a prezentují pouze informace požadované podle příslušných selektorů.

Screenshot diagramu selektorů akce

Chcete-li vytvořit nový selektor akce, nejprve vytvořte základní akci, kterou budou selektory používat.

Centrální akce vyžaduje buď logickou vlastnost nebo vlastnost výčtu jako vstupní argument C#.

Hodnota této vlastnosti určuje, který selektor se použije.

Nejběžnějším způsobem je použití výčtu. Zvláště když jsou potřeba více než dva selektory, je výčet jedinou možností.

Pro dva případy selektoru lze použít logické hodnoty.

Tato vlastnost, známá také jako argument omezení, musí mít výchozí hodnotu.

Ústřední akce je deklarována jako klasická akce.

Všimněte si, že první vlastností (vstupní argument) je výčet. Na základě hodnoty této vlastnosti se aktivuje příslušný selektor.

Poznámka:

Chcete-li mít argumenty seřazeny požadovaným způsobem, nastavte hodnotu Order vedle atributu 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
}

Selektory vlastní akce používající výčty

V tomto příkladu vytvoříte tři selektory. Jednoduchý výčet pokaždé určí příslušný selektor:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Selektory jsou reprezentovány třídami.

Tyto třídy musí zdědit třídu ActionSelector<TBaseActionClass>.

Poznámka:

TBaseActionClass je název třídy základní akce.

V metodě UseName() je deklarován název selektoru akce. Ten slouží jako název akce k rozpoznání zdrojů.

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

Poznámka:

Třídy Selector by neměly být deklarovány jako akce. Jediná akce je ta centrální. Selektory fungují jako filtry.

V tomto konkrétním příkladu chceme zobrazit pouze jeden z argumentů, takže ostatní jsou odfiltrovány. Podobně pro třídy Selector2:

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

a Selector3:

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

Konečné spuštění je dosaženo pomocí metody Execute(ActionContext context), která je součástí centrální akce. Na základě selektoru se zobrazí příslušné filtrované hodnoty.

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

Selektor vlastní akce používající logickou hodnotu

Následuje příklad využívající logický typ místo výčtu.

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

Popisy nastavení pro selektory vlastní akce

Chcete-li vytvořit popis a souhrn pro selektory, použijte následující formát v souboru .resx vašeho vlastního modulu.

SelectorName_Description
SelectorName_Summary

To lze také provést v selektoru pomocí metod WithDescription a WithSummary.

Důležité

Soubory .dll popisující vlastní akce, jejich závislosti .dll a soubor .cab obsahující vše by měly být řádně podepsány digitálním certifikátem, kterému vaše organizace důvěřuje. Certifikát by měl být také nainstalován na každém počítači, kde se vytváří/upravují/spouští desktopové toky se závislostmi vlastních akcí, a nacházel by se pod důvěryhodnou kořenovou certifikační autoritou.

ID vlastních modulů

Každý modul má své vlastní ID (název sestavy). Při vytváření vlastních modulů se ujistěte, že jste nastavili jedinečná ID modulu. Chcete-li nastavit název sestavy vašeho modulu, upravte vlastnost Název sestavy v části Obecné vlastností projektu C#.

Upozorňující

Zahrnutí modulů se stejným ID do toku povede ke konfliktům

Konvence názvů vlastních modulů

Aby byly vlastní moduly čitelné přes Power Automate pro desktopy, AssemblyName musí mít název souboru podle následujícího vzoru:

?*.Modules.?*
Modules.?*

Například Modules.ContosoActions.dll

AssemblyTitle v nastavení projektu určuje ID modulu. Může obsahovat pouze alfanumerické znaky a podtržítka a musí začínat písmenem.

Podepište všechny knihovny DLL uvnitř vlastního modulu

Důležité

Je povinné mít všechny soubory .dll, které obsahují vlastní modul (vygenerovaná sestava a všechny jeho závislosti) podepsané důvěryhodným certifikátem

Pro dokončení vytváření vlastního modulu je nutné podepsat všechny vygenerované soubory .dll, které lze nalézt ve složce bin/release nebo bin/Debug projektu.

Podepište všechny soubory .dll pomocí důvěryhodného certifikátu spuštěním následujícího příkazu (pro každý soubor .dll) v příkazovém řádku vývojáře pro Visual Studio:

Podepište soubory .dll pomocí důvěryhodného certifikátu spuštěním následujícího příkazu (pro každý soubor .dll) v příkazovém řádku vývojáře pro 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

Nebo spuštěním následujícího příkazu (vytvořením skriptu Windows PowerShell .ps1), který iteruje všechny soubory .dll a podepíše každý z nich poskytnutým certifikátem:

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
}

Poznámka:

Digitální certifikát musí mít exportovatelný soukromý klíč a možnosti podepisování kódu.

Zabalení všeho do souboru CAB

Soubor .dll obsahující vlastní akce a všechny jejich závislosti (soubory .dll) musí být zabaleny do souboru CAB (.cab).

Poznámka:

Při pojmenovávání souboru CAB se řiďte konvencí pojmenování souborů a složek pro operační systém Windows. Nepoužívejte mezery nebo speciální znaky jako < > : " / \ | ? * .

Vytvořte skript Windows PowerShell (.ps1) obsahující následující řádky:

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

Tento skript Windows PowerShell lze poté použít k vytvoření souboru CAB jeho vyvoláním v prostředí Windows PowerShell a zadáním:

  • Adresáře souborů DLL, které mají být komprimovány.
  • Cílového adresáře, do kterého se má umístit vygenerovaný soubor CAB.

Vyvolejte skript pomocí následující syntaxe:

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

Příklad:

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

Poznámka:

  • Při vytváření souboru CAB se ujistěte, že skutečný soubor DLL vlastních akcí je v kořenové úrovni cílové cesty a ne v podsložce.
  • Soubor CAB musí být také podepsán. Nepodepsané soubory CAB nebo v nich obsažené nepodepsané knihovny DLL nebudou použitelné v desktopových tocích a při jejich zahrnutí způsobí chybu.

Další kroky

Nahrání vlastních akcí