Zdieľať cez

Vytvorte Power Automate pre akcie na počítači pomocou súpravy Actions SDK

  • Článok

Tento článok popisuje, ako vytvoriť vlastné akcie v Power Automate pre počítač.

Vytváranie vlastných akcií

Dôležité

Rezervované kľúčové slová nemožno použiť ako názvy akcií a/alebo vlastnosti akcií. Použitie vyhradených kľúčových slov ako názvov akcií a/alebo vlastností akcií vedie k chybnému správaniu. Ďalšie informácie: Vyhradené kľúčové slová v postupoch pre počítače

Začnite vytvorením nového projektu Class Library (.NET Framework). Vyberte verziu .NET frameworku 4.7.2.

Ak chcete vytvoriť akciu vo vytvorenom vlastnom module:

  • Odstráňte automaticky vygenerovaný súbor Class1.cs.
  • Vytvorte novú triedu vo svojom projekte, ktorá bude reprezentovať vlastnú akciu, a dajte jej odlišný názov.
  • Zahrňte priestory názvov Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK a Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes.
  • Všetky triedy reprezentujúce akcie by mali mať nad vašou triedou atribút [Action].
  • Trieda by mala mať verejný prístup a dediť z triedy 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äčšina akcií má parametre (vstup alebo výstup). Vstupné a výstupné parametre sú reprezentované klasickými vlastnosťami jazyka C#. Každá vlastnosť by mala mať vhodný atribút C#, buď [InputArgument] alebo [OutputArgument] na diktovanie jej typu a spôsobu zobrazenia v Power Automate pre počítač. Vstupné argumenty môžu mať aj predvolené 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}";
        }
    }
}

Pridávanie popisov k vlastným akciám

Pridajte popis a priateľský názov pre moduly a akcie, aby vývojári RPA vedeli, ako ich najlepšie využiť.

Power Automate pre desktop designer zobrazuje priateľské názvy a popisy.

Môžete vytvoriť súbor "Resources.resx" v priečinku Vlastnosti projektu modulu. Nový súbor „.resx“ by mal mať názov „Resources.resx“.

Formát popisov modulov a akcií by mal byť takýto:

"Module_Description" alebo "Action_Description" a "Module_FriendlyName" alebo "Action_FriendlyName" v danom poradí v poli názvu. Popis v poli hodnoty.

Odporúčame tiež uviesť popisy a popisné názvy parametrov. Ich formát by mal byť nasledovný: „Popis_parametra_akcie“, „Názov_parametra_akcie“.

Snímka obrazovky zdrojov pre jednoduchú akciu

Prepitné

Do poľa komentára sa odporúča uviesť, čo popisujete (napr. Modul, Akcia atď.)

Tie je možné nastaviť aj pomocou vlastností FriendlyName a Description atribútov [InputArgument], [OutputArgument] a [Action] .

Tu je príklad súboru Resources.resx pre vlastný modul.

Snímka obrazovky Zdroje

Ďalším spôsobom, ako rýchlo pridať priateľské názvy a popisy k akciám a parametrom, sú vlastnosti FriendlyName a Description v [Action], [InputArguement] a [OutputArguement] atribúty.

Poznámka

Ak chcete do modulu pridať popisný názov a popis, musíte upraviť príslušný súbor .resx alebo pridať príslušné atribúty C#.

Lokalizácia zdrojov

Predpokladá sa, že predvolený jazyk modulov v Power Automate pre počítač je angličtina.

Súbor Resources.resx by mal byť v angličtine.

Akékoľvek ďalšie jazyky môžu byť pridané pomocou ďalších zdrojov.{locale}.resx súborov na lokalizáciu. Napríklad Resources.fr.resx.

Kategórie vlastných modulov

Moduly môžu obsahovať kategórie a podkategórie pre lepšiu organizáciu akcií.

Ak chcete oddeliť vlastné akcie v kategóriách, podkategóriách, upravte atribút [Action] , ktorý predchádza triede, ktorá predstavuje vlastnú akciu, nasledujúcim spôsobom:

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

Poznámka

Modul môže mať viacero kategórií. Podobne môžu byť kategórie zložené do podkategórií. Táto štruktúra môže byť neurčitá.

Vlastnosť Order určuje poradie, podľa ktorého sa ukážky akcií v návrhárovi zobrazujú.

Action1 patrí do kategórie "TestCategory" a je to prvá akcia modulu (takto vysvetľujete Objednávku a kategóriu na príklade).

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

Podmienečné akcie

Podmienené akcie sú akcie, ktoré vrátia hodnotu „Pravda“ alebo „Nepravda“. 'Ak súbor existuje' Power Automate pre počítačovú akciu štandardnej knižnice je dobrým príkladom podmienenej akcie.

Príklad podmienenej akcie:

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šimnite si logickú premennú Výsledok .

Akcia Ak súbor existuje nemá výstupný argument. To, čo vráti, je buď pravda alebo nepravda, v závislosti od toho, čo obsahuje booleovská premenná Výsledok .

Vlastné selektory akcií

Existujú konkrétne prípady, v ktorých sa môže vyžadovať, aby vlastná akcia mala viac ako jednu variáciu.

Príkladom je akcia „Spustiť Excel“ zo štandardnej knižnice akcií.

Pomocou selektora „s prázdnym dokumentom“ tok spustí prázdny dokument programu Excel, zatiaľ čo výber „a otvoriť nasledujúci dokument“ vyžaduje na otvorenie cestu k súboru.

Snímka obrazovky s výberom akcií programu Excel

Dve vyššie uvedené akcie sú dva selektory základnej akcie "Spustiť Excel".

Pri vytváraní vlastných akcií nemusíte prepisovať funkčnosť.

Môžete vytvoriť jednu „základnú“ akciu, nastaviť jej vstupné a výstupné parametre a potom pomocou selektorov akcií zvoliť, čo bude viditeľné v každej verzii.

Prostredníctvom selektorov akcií možno k jednej akcii pridať úroveň abstrakcie, čo umožňuje získať špecifickú funkčnosť z jedinej „základnej“ akcie bez toho, aby ste museli prepisovať kód, aby sa zakaždým vytvorila nová variácia tej istej akcie.

Premýšľajte o selektoroch ako o možnostiach, ktoré filtrujú jednu akciu a prezentujú len informácie požadované podľa príslušných selektorov.

Snímka obrazovky diagramu selektorov akcií

Ak chcete vytvoriť nový selektor akcie, najprv vytvorte základnú akciu, ktorú budú selektory využívať.

Centrálna akcia vyžaduje buď boolovskú alebo vlastnosť enumerácia ako vstupný argument C#.

Hodnota tejto vlastnosti určuje, ktorý selektor sa použije.

Najbežnejším spôsobom je použitie enumerácia. Najmä ak sú potrebné viac ako dva selektory, enumy sú jedinou možnosťou.

Pre dva prípady selektora možno použiť boolovské hodnoty.

Táto vlastnosť, známa aj ako argument obmedzenia, musí mať predvolenú hodnotu.

Ústredná akcia je deklarovaná ako klasická akcia.

Všimnite si, že prvá vlastnosť (vstupný argument) je enumerácia. Na základe hodnoty tejto vlastnosti sa aktivuje príslušný selektor.

Poznámka

Ak chcete, aby boli argumenty usporiadané požadovaným spôsobom, nastavte hodnotu Order vedľa atribútu 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
}

Vlastné selektory akcií pomocou enumov

V tomto príklade vytvoríte tri selektory. Jednoduchý enumerácia zakaždým diktuje vhodný selektor:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Selektory sú reprezentované triedami.

Tieto triedy musia zdediť triedu ActionSelector<TBaseActionClass> .

Poznámka

TBaseActionClass je názov základnej triedy akcií.

V metóde UseName() je deklarovaný názov selektora akcie. Používa sa ako názov akcie na vyriešenie zdrojov.

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

Triedy Selektor by sa nemali deklarovať ako akcie. Jediná akcia je centrálna. Selektory fungujú ako filtre.

V tomto konkrétnom príklade chceme zobraziť iba jeden z argumentov, takže ostatné sú odfiltrované. Podobne pre Selektor2:

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

A Selector3 triedy:

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

Konečné vykonanie sa dosiahne pomocou metódy Execute (kontext kontextu akcie) , ktorá sa nachádza v centrálnej akcii. Na základe voliča sa zobrazia prí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}";
    }
}

Vlastné selektory akcií pomocou boolovských hodnôt

Nasleduje príklad využívajúci Boolean namiesto enumov.

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í pre selektory vlastných akcií

Ak chcete vytvoriť popis a súhrn pre selektory, použite nasledujúci formát v súbore .resx vášho vlastného modulu.

SelectorName_Description
SelectorName_Summary

Dá sa to urobiť aj vo selektore metódami WithDescription a WithSummary.

Dôležité

Súbory .dll popisujúce vlastné akcie, ich závislosti .dll a súbor .cab obsahujúci všetko by mali byť riadne podpísané digitálnym certifikátom, ktorému vaša organizácia dôveruje. Certifikát by mal byť nainštalovaný aj na každom počítači, na ktorom je vytvorený/upravený/vykonaný postup v počítačovom prostredí so závislosťami vlastných akcií, ktorý sa nachádza pod dôveryhodnými koreňovými certifikačnými autoritami.

ID vlastných modulov

Každý modul má svoje vlastné ID (názov zostavy). Pri vytváraní vlastných modulov sa uistite, že ste nastavili jedinečné ID modulov. Ak chcete nastaviť názov zostavy vášho modulu, upravte vlastnosť Názov zostavy v sekcii Všeobecné vo vlastnostiach projektu C#.

Upozornenie

Zahrnutie modulov s rovnakým ID do toku bude mať za následok konflikty

Vlastné konvencie názvov modulov

Aby boli vlastné moduly čitateľné cez Power Automate pre desktop, AssemblyName musí mať názov súboru podľa nasledujúceho vzoru:

?*.Modules.?*
Modules.?*

Napríklad Moduly.ContosoActions.dll

AssemblyTitle v nastaveniach projektu určuje ID modulu. Môže obsahovať iba alfanumerické znaky a podčiarkovníky a musí začínať písmenom.

Podpíšte všetky knižnice DLL vo vlastnom module

Dôležité

Je povinné mať všetky súbory .dll, ktoré tvoria vlastný modul (vygenerovaná zostava a všetky jej závislosti) podpísané dôveryhodným certifikátom

Na dokončenie vytvárania vlastného modulu musia byť podpísané všetky vygenerované súbory .dll, ktoré sa nachádzajú v priečinku bin/release alebo bin/Debug projektu.

Podpíšte všetky súbory .dll pomocou dôveryhodného certifikátu spustením nasledujúceho príkazu (pre každý súbor .dll) v príkazovom riadku vývojára pre Visual Studio:

Podpíšte súbory .dll pomocou dôveryhodného certifikátu spustením nasledujúceho príkazu (pre každú knižnicu dll) v príkazovom riadku vývojára pre 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

Alebo spustením nasledujúceho príkazu (vytvorením skriptu Windows PowerShell .ps1), ktorý iteruje všetky súbory .dll a každý z nich podpíše poskytnutým certifikátom:

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álny certifikát musí mať exportovateľný súkromný kľúč a možnosti kódového podpisu

Zabalenie všetkého do kabinetu

.dll obsahujúca vlastné akcie a všetky ich závislosti (súbory .dll) musia byť zabalené v súbore kabinetu (.cab).

Poznámka

Pri pomenovaní súboru .cab sa riaďte konvenciou pomenovávania súborov a priečinkov pre operačný systém Windows. Nepoužívajte medzery alebo špeciálne znaky ako napr < > : " / \ | ? * .

Vytvorte skript Windows PowerShell (.ps1) obsahujúci nasledujúce riadky:

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 prostredia Windows PowerShell potom možno použiť na vytvorenie súboru .cab jeho vyvolaním v prostredí Windows PowerShell a poskytnutím:

  • Adresár so súbormi .dll, ktoré sa majú komprimovať.
  • Cieľový adresár, do ktorého sa má umiestniť vygenerovaný súbor .cab.

Vyvolajte skript pomocou nasledujúcej 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

Príklad:

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

Poznámka

  • Pri vytváraní súboru .cab sa uistite, že skutočný súbor .dll vlastných akcií je na koreňovej úrovni cieľovej cesty a nie v podpriečinku.
  • Súbor .cab musí byť tiež podpísaný. Nepodpísané súbory .cab a/alebo nepodpísané súbory .dll, ktoré sa v nich nachádzajú, nebudú použiteľné v postupoch na pracovnej ploche a počas zahrnutia spôsobia chybu.

Ďalšie kroky

Nahrajte vlastné akcie