Létrehozás Power Automate asztali műveletekhez az Actions SDK használatával

Cikk
08/05/2024

Ez a cikk azt ismerteti, hogyan hozhat létre egyéni műveleteket az asztali környezetben Power Automate .

Egyéni műveletek létrehozása

Fontos

A fenntartott kulcsszavak nem használhatók műveletnévként és/vagy művelettulajdonságként. A fenntartott kulcsszavak műveletnévként és/vagy művelettulajdonságként való használata hibás viselkedést eredményez. További információ: Fenntartott kulcsszavak az asztali folyamatokban

Először hozzon létre egy új osztálykönyvtári (.NET-keretrendszer) projektet. Válassza .NET-keretrendszer 4.7.2-es verziót.

Művelet létrehozása a létrehozott egyéni modulban:

Törölje az automatikusan létrehozott Class1.cs fájlt.
Hozzon létre egy új osztályt a projekten belül, amely az egyéni műveletet képviseli, és adjon neki egy külön nevet.
Foglalja bele a Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK és a Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes névtereket.
A műveleteket képviselő összes osztálynak rendelkeznie kell egy [Action] attribútummal az osztály felett.
Az osztálynak nyilvános hozzáféréssel kell rendelkeznie, és örökölnie kell az ActionBase osztálytól.

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

A legtöbb művelet paraméterekkel rendelkezik (bemenet vagy kimenet). A bemeneti és kimeneti paramétereket klasszikus C#-tulajdonságok képviselik. Minden tulajdonságnak rendelkeznie kell egy megfelelő C# attribútummal, vagy [InputArgument] [OutputArgument] vagy a típusának és az asztali megjelenítés módjának Power Automate diktálásához. A bemeneti argumentumok alapértelmezett értékekkel is rendelkezhetnek.

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

Leírások hozzáadása egyéni műveletekhez

Adja meg a modulok és műveletek leírását és rövid nevét, hogy az RPA-fejlesztők tudják, hogyan használhatják ki őket a legjobban.

Power Automate A Desktop Designer rövid neveket és leírásokat jelenít meg.

Létrehozhat egy "Resources.resx" fájlt a modulprojekt Tulajdonságok mappájában. Az új ".resx" fájl neve "".Resources.resx

A modulok és műveletek leírásának formátuma a következő:

"Module_Description" vagy "Action_Description" és "Module_FriendlyName" vagy "Action_FriendlyName" a név mezőben. Az értékmezőben szereplő leírás.

Azt is javasoljuk, hogy adjon meg leírásokat és rövid neveket a paraméterekhez. Formátumuk a következő: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Képernyőkép: Erőforrások egy egyszerű művelethez

Tipp.

Javasoljuk, hogy jelölje meg, hogy mit ír le a megjegyzés mezőben (pl. Modul, Művelet stb.)

Ezek a FriendlyName és a Description attribútumok [InputArgument] tulajdonságaival is beállíthatók. [OutputArgument] [Action]

Az alábbi példa Resources.resx egy egyéni modul fájlját mutatja be.

Képernyőkép az erőforrásokról

Egy másik módja annak, hogy gyorsan adjon rövid neveket és leírásokat a műveletekhez és paraméterekhez, a FriendlyName és a Description tulajdonság használata a [Action], [InputArguement] and [OutputArguement] attribútumokban.

Feljegyzés

Ha rövid nevet és leírást szeretne hozzáadni egy modulhoz, módosítania kell a megfelelő .resx fájlt, vagy hozzá kell adnia a megfelelő C#-attribútumokat.

Erőforrások honosítása

Az asztali modulok Power Automate alapértelmezett nyelve az angol.

A Resources.resx fájlnak angol nyelvűnek kell lennie.

Bármely más nyelv hozzáadható extra erőforrásokkal.{locale} resx fájlok honosításhoz. Például, Resources.fr.resx.

Egyéni modulkategóriák

A modulok kategóriákat és alkategóriákat tartalmazhatnak a jobb műveletszervezés érdekében.

Az egyéni műveletek kategóriákban, alkategóriákban való elkülönítéséhez módosítsa az egyéni műveletet képviselő osztály előtti [Action] attribútumot a következő módon:

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

Feljegyzés

Egy modulnak több kategóriája is lehet. Hasonlóképpen, a kategóriák alkategóriákból is állhatnak. Ez a szerkezet határozatlan lehet.

Az Order tulajdonság határozza meg, hogy a tervezőben milyen sorrendben jelenjen meg a műveletek előnézete.

Action1 a "TestCategory" kategóriába tartozik, és ez a modul első művelete (így egy példával magyarázza el a sorrendet és a kategóriát).

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

Feltételes műveletek

A feltételes műveletek olyan műveletek, amelyek "Igaz" vagy "Hamis" értéket adnak vissza. A szabványos könyvtár asztali műveletének "Ha létezik fájl" Power Automate jó példája a feltételes műveletnek.

Példa feltételes műveletre:

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

Figyelje meg az Eredmény logikai változót.

A Ha a fájl létezik műveletnek nincs kimeneti argumentuma. Amit visszaad, az igaz vagy hamis, attól függően, hogy mit tartalmaz az Result logikai változó .

Egyéni műveletválasztók

Vannak olyan speciális esetek, amikor egy egyéni műveletnek egynél több változattal kell rendelkeznie.

Példa erre az "Excel indítása" művelet, a szabványos művelettárból.

Az "üres dokumentummal" választóval a folyamat elindít egy üres Excel-dokumentumot, míg az "és nyissa meg a következő dokumentumot" beállítás használatához meg kell nyitni a fájl elérési útját.

Képernyőkép: Az Excel indítása műveletválasztók

A fent említett két művelet az "Excel indítása" alapművelet két választója.

Egyéni műveletek létrehozásakor nem kell újraírnia a funkciókat.

Létrehozhat egyetlen "alap" műveletet, beállíthatja annak bemeneti és kimeneti paramétereit, majd műveletválasztók használatával kiválaszthatja, hogy mi legyen látható az egyes ízekben.

A műveletválasztókon keresztül egy absztrakciós szint adható hozzá egyetlen művelethez, lehetővé téve bizonyos funkciók visszakeresését egyetlen "alapműveletből" anélkül, hogy újra kellene írni a kódot, hogy minden alkalommal ugyanannak a műveletnek egy új változatát hozza létre.

Gondoljon úgy a választókra, mint választási lehetőségekre, amelyek egyetlen műveletet szűrnek, és csak a szükséges információkat jelenítik meg a megfelelő választók szerint.

Képernyőkép a műveletválasztók diagramjáról

Új műveletválasztó létrehozásához először hozzon létre egy alapműveletet, amelyet a választók használhatnak.

A központi művelethez bemeneti C#-argumentumként logikai vagy felsorolás tulajdonságra van szükség.

Ennek a tulajdonságnak az értéke határozza meg, hogy melyik választót használja.

A leggyakoribb módszer a felsorolás használata. Különösen akkor, ha kettőnél több választóra van szükség, az enumok az egyetlen lehetőség.

Két szelektor esetben logikai értékek használhatók.

Ennek a tulajdonságnak, más néven megszorítási argumentumnak, alapértelmezett értékkel kell rendelkeznie.

A központi akció klasszikus akciónak minősül.

Figyelje meg, hogy az első tulajdonság (bemeneti argumentum) egy felsorolás. A tulajdonság értéke alapján a megfelelő választó aktívvá válik.

Feljegyzés

Az argumentumok kívánt módon történő rendezéséhez állítsa be az Order értéket az InputArgument attribútum mellett.

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
}

Egyéni műveletválasztók felsorolások használatával

Ebben a példában három választót hoz létre. Egy egyszerű felsorolás minden alkalommal diktálja a megfelelő választót:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

A szelektorokat osztályok képviselik.

Ezeknek az osztályoknak öröklik az ActionSelector<TBaseActionClass> osztályt.

Feljegyzés

A TBaseActionClass az alapműveletosztály neve.

A UseName() metódusban a műveletválasztó neve deklarálva van. Ez az erőforrások feloldására szolgáló művelet neve.

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

Feljegyzés

A választóosztályok nem deklarálhatók műveletként. Az egyetlen cselekvés a központi. A szelektorok szűrőként működnek.

Ebben a konkrét példában csak az egyik argumentumot szeretnénk megjeleníteni, így a többit kiszűrjük. Hasonlóképpen a Selector2 esetében:

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

És Selector3 osztályok:

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

A végső végrehajtás a központi műveletben található Execute(ActionContext context) metódussal érhető el. A választó alapján megjelennek a megfelelő szűrt értékek.

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

Egyéni műveletválasztók logikai használatával

Az alábbi példa egy olyan példát mutat be, amely logikai használ felsorolások helyett.

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

Egyéni műveletválasztók leírásának beállítása

A választók leírásának és összegzésének létrehozásához használja a következő formátumot az egyéni modul .resx fájljában.

SelectorName_Description
SelectorName_Summary

Ez a választóban is elvégezhető a WithDescription és a WithSummary metódussal.

Fontos

. DLL az egyéni műveleteket leíró fájlok, azok . DLL függőségeket és a mindent tartalmazó .cab fájlt megfelelően alá kell írni a szervezet által megbízhatónak ítélt digitális tanúsítvánnyal. A tanúsítványt minden olyan gépre telepíteni kell, amelyen egyéni műveletfüggőségekkel rendelkező asztali folyamat írt/módosított/hajtott végre, amelyek a megbízható legfelső szintű hitelesítésszolgáltatók alatt találhatók.

Egyéni modulazonosítók

Minden modulnak saját azonosítója van (szerelvény neve). Egyéni modulok létrehozásakor győződjön meg arról, hogy egyedi modulazonosítókat állít be. A modul szerelvénynevének beállításához módosítsa a szerelvény neve tulajdonságot a C#-projekt tulajdonságainak Általános szakaszában.

Figyelmeztetés:

Az azonos azonosítóval rendelkező modulok folyamatba való belefoglalása ütközéseket eredményez

Egyéni modulnév-konvenciók

Ahhoz, hogy az egyéni modulok olvashatók Power Automate legyenek az asztalon, az AssemblyName fájlnévnek az alábbi mintát követő fájlnévvel kell rendelkeznie:

?*.Modules.?*
Modules.?*

Például,Modulok . ContosoActions. DLL

A projektbeállításokban az AssemblyTitle határozza meg a modul azonosítóját. Csak alfanumerikus karaktereket és aláhúzásjeleket tartalmazhat, és betűvel kell kezdődnie.

Az egyéni modulon belüli összes DLL-fájl aláírása

Fontos

Kötelező, hogy az összes . DLL fájlok egy megbízható tanúsítvánnyal aláírt egyéni modult (generált szerelvényt és annak összes függőségét) tartalmaznak

Az egyéni modul létrehozásának véglegesítéséhez az összes generált . DLL fájlokat, amelyek a projekt bin/release vagy bin/Debug mappájában találhatók, alá kell írni.

Írja alá az összes . DLL fájlokat megbízható tanúsítvánnyal a következő parancs futtatásával (minden .DLL fájlhoz) egy fejlesztői parancssorban a következőhöz Visual Studio:

Írja alá a .dlls fájlokat egy megbízható tanúsítvány használatával a következő parancs futtatásával (minden DLL esetében) egy fejlesztői parancssorban a következőhöz 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

Vagy a következő parancs futtatásával (egy .ps1 Windows PowerShell-parancsfájl létrehozásával), amely végighalad az összes . DLL fájlokat, és mindegyiket aláírja a megadott tanúsítvánnyal:

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
}

Feljegyzés

A digitális tanúsítványnak exportálható személyes kulccsal és kódaláírási képességgel kell rendelkeznie

Mindent egy kabinetfájl csomagol

A. DLL egyéni műveleteket és azok összes függőségét (.DLL fájlokat) tartalmazó kabinetfájl (.cab) kell csomagolni.

Feljegyzés

A .cab fájl elnevezésekor kövesse a Windows operációs rendszer fájl- és mappaelnevezési konvencióját. Ne használjon üres szóközöket vagy speciális karaktereket, < > : " / \ | ? * például.

Hozzon létre egy Windows PowerShell-parancsfájlt (.ps1), amely a következő sorokat tartalmazza:

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

Ez a Windows PowerShell-parancsfájl ezután használható a .cab fájl létrehozására úgy, hogy meghívja azt a Windows PowerShellben, és biztosítja a következőket:

A könyvtára a . DLL tömörítendő fájlokat.
A létrehozott .cab fájl elhelyezésére szolgáló célkönyvtár.

Hívja meg a parancsfájlt a következő szintaxissal:

.\{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élda:

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

Feljegyzés

Győződjön meg arról, hogy a tényleges egyéni műveletek . DLL fájl a .cab fájl létrehozásakor a célzott elérési út gyökérszintjén van, nem pedig egy almappában.
A .cab fájlt is alá kell írni. Az aláíratlan .cab fájlok és/vagy a bennük található aláíratlan .dll-fájlok nem használhatók az asztali folyamatokban, és hibát okoznak a felvétel során.

További lépések

Egyéni műveletek feltöltése

Megosztás a következőn keresztül:

Létrehozás Power Automate asztali műveletekhez az Actions SDK használatával

Egyéni műveletek létrehozása

Leírások hozzáadása egyéni műveletekhez

Erőforrások honosítása

Egyéni modulkategóriák

Feltételes műveletek

Egyéni műveletválasztók

Egyéni műveletválasztók felsorolások használatával

Egyéni műveletválasztók logikai használatával

Egyéni műveletválasztók leírásának beállítása

Egyéni modulazonosítók

Egyéni modulnév-konvenciók

Az egyéni modulon belüli összes DLL-fájl aláírása

Mindent egy kabinetfájl csomagol

További lépések

Visszajelzés

További források

Megosztás a következőn keresztül:

Létrehozás Power Automate asztali műveletekhez az Actions SDK használatával

Egyéni műveletek létrehozása

Leírások hozzáadása egyéni műveletekhez

Erőforrások honosítása

Egyéni modulkategóriák

Feltételes műveletek

Egyéni műveletválasztók

Egyéni műveletválasztók felsorolások használatával

Egyéni műveletválasztók logikai használatával

Egyéni műveletválasztók leírásának beállítása

Egyéni modulazonosítók

Egyéni modulnév-konvenciók

Az egyéni modulon belüli összes DLL-fájl aláírása

Mindent egy kabinetfájl csomagol

További lépések

Kapcsolódó információk

Visszajelzés

További források