Acties voor Power Automate voor bureaublad maken met de Acties voor SDK
In dit artikel wordt beschreven hoe u aangepaste acties maakt in Power Automate voor bureaublad.
Aangepaste acties maken
Belangrijk
Gereserveerde trefwoorden kunnen niet worden gebruikt als actienamen en/of actie-eigenschappen. Gebruik van gereserveerde trefwoorden als actienamen en/of actie-eigenschappen resulteert in foutief gedrag. Meer informatie: Gereserveerde trefwoorden in bureaubladstromen
Maak als eerste een nieuw klassebibliotheekproject (.NET Framework). Selecteer .NET Framework versie 4.7.2.
U kunt als volgt een actie vormen in de gemaakte aangepaste module:
- Verwijder het automatisch gegenereerde bestand Class1.cs.
- Maak een nieuwe klasse binnen uw project om de aangepaste actie weer te geven en geef deze een aparte naam.
- Neem de naamruimten Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK en Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes op.
- Alle klassen die acties vertegenwoordigen, moeten een kenmerk [Action] boven uw klasse hebben.
- De klasse moet openbare toegang hebben en overnemen van de klasse 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();
}
}
}
De meeste acties parameters (invoer of uitvoer). Invoer- en uitvoerparameters worden weergegeven door klassieke C#-eigenschappen.
Elke eigenschap moet een geschikt C#-kenmerk, [InputArgument] of [OutputArgument], hebben om het type te bepalen en aan te geven hoe ze worden gepresenteerd in Power Automate voor bureaublad.
Invoerargumenten kunnen ook standaardwaarden hebben.
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}";
}
}
}
Beschrijvingen toevoegen aan aangepaste acties
Voeg een beschrijving en een beschrijvende naam toe voor de modules en acties, zodat RPA-ontwikkelaars weten hoe ze deze het beste kunnen gebruiken.
De ontwerper van Power Automate voor bureaublad toont beschrijvende namen en beschrijvingen.
U kunt een bestand "Resources.resx" maken in de map Eigenschappen van het moduleproject. Het nieuwe ".resx"-bestand zou de naam "Resources.resx" moeten krijgen.
De indeling van de beschrijvingen voor modules en acties moet als volgt zijn:
"Module_Description" of "Action_Description" en respectievelijk "Module_FriendlyName" of "Action_FriendlyName" in het naamveld. De beschrijving in het waardeveld.
We raden u ook aan beschrijvingen en beschrijvende namen voor parameters op te geven. Hun indeling moet als volgt zijn: "Action_Parameter_Description", "Action_Parameter_FriendlyName".
Tip
Het wordt aanbevolen om aan te geven wat u beschrijft in het opmerkingenveld (bijv. Module, Actie enz.)
Deze kunnen ook worden ingesteld met de eigenschappen FriendlyName en Description van de kenmerken [InputArgument], [OutputArgument] en [Action].
Hier is een voorbeeld van een bestand Resources.resx voor een aangepaste module.
Een andere manier om snel beschrijvende namen en beschrijvingen aan acties en parameters toe te voegen, is met de eigenschappen FriendlyName en Description in de kenmerken [Action], [InputArguement] en [OutputArguement].
Opmerking
Als u een beschrijvende naam en een beschrijving aan een module wilt toevoegen, moet u het respectieve .resx-bestand wijzigen of de respectieve C#-kenmerken toevoegen.
Foutverwerking toevoegen aan aangepaste acties
Als u aangepaste uitzonderingen in uw actie wilt definiëren, gebruikt u het kenmerk [Throws("ActionError")] boven de aangepaste actieklasse. Elk uitzonderingsgeval dat u wilt definiëren, moet een eigen kenmerk hebben.
Gebruik de volgende code in het catch-blok:
throw new ActionException("ActionError", e.Message, e.InnerException);
Zorg ervoor dat de ActionException-naam overeenkomt met de naam die u in het kenmerk Throws hebt opgegeven. Gebruik throw new ActionException voor elk uitzonderingsgeval en koppel het aan de bijbehorende Throws kenmerknaam. Alle uitzonderingen die zijn gedefinieerd met het kenmerk Throws zijn zichtbaar op het tabblad Foutafhandeling van actie van de ontwerper.
Een voorbeeld hiervan is te vinden in de sectie Voorwaardelijke acties .
Lokalisatie van resources
De standaardtaal voor modules in Power Automate voor bureaublad wordt verondersteld Engels te zijn.
Het bestand Resources.resx moet in het Engels zijn.
Alle andere talen kunnen worden toegevoegd met extra Resources.{locale}.resx-bestanden voor lokalisatie. Bijvoorbeeld: Resources.fr.resx.
Categorieën van aangepaste modules
Modules kunnen categorieën en subcategorieën bevatten voor een betere ordening van acties.
Als u aangepaste acties wilt scheiden in categorieën, subcategorieën, wijzigt u als volgt het kenmerk [Action] dat voorafgaat aan de klasse die de aangepaste actie vertegenwoordigt:
[Action(Category = "category.subcategory")]
Opmerking
Een module kan in meerdere categorieën vallen. Evenzo kunnen categorieën zijn samengesteld uit subcategorieën. Deze structuur kan onbepaald zijn.
De eigenschap Order bepaalt de volgorde waarin acties worden weergegeven in de ontwerper.
Action1 valt in de categorie 'TestCategory' en is de eerste actie van de module (zo legt u Volgorde en categorie uit met een voorbeeld).
[Action(Id = "Action1", Order = 1, Category = "TestCategory")]
Voorwaardelijke acties
Voorwaardelijke acties zijn acties die "True" of "False" retourneren. De Power Automate voor bureaubladactie 'If file exists' van de standaardbibliotheek is een goed voorbeeld van een voorwaardelijke actie.
Voorbeeld van voorwaardelijke actie:
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
}
}
Let op de booleaanse variabele Result.
De actie If file exists heeft geen uitvoerargument. Wat het retourneert is true of false, afhankelijk van wat de booleaanse variabele Result bevat.
Selectors voor aangepaste acties
Er zijn bepaalde gevallen waarin een aangepaste actie nodig kan zijn om meer dan één variatie te hebben.
Een voorbeeld is de actie "Launch Excel", uit de standaardbibliotheek met acties.
Met behulp van de selector "with a blank document" start de stroom een leeg Excel-document, terwijl het gebruik van de selectie "and open the following document" vereist dat het bestandspad van het bestand wordt geopend.
De twee hierboven genoemde acties zijn twee selectors van de basisactie "Launch Excel".
Wanneer u aangepaste acties maakt, hoeft u geen functionaliteit te herschrijven.
U kunt een enkele "basisactie" maken, de invoer- en uitvoerparameters instellen en vervolgens kiezen wat zichtbaar is in elke variant door gebruik te maken van actieselectors.
Door middel van actieselectors kan een abstractieniveau worden toegevoegd aan een enkele actie, waardoor specifieke functionaliteit uit de enkele "basisactie" kan worden opgehaald zonder dat code hoeft te worden herschreven om elke keer een nieuwe variant van dezelfde actie te vormen.
Beschouw selectors als keuzes, waarbij een enkele actie wordt gefilterd en alleen de informatie wordt gepresenteerd die nodig is voor de respectievelijke selectors.
Als u een nieuwe actieselector wilt vormen, maakt u eerst een basisactie die door de selectors moet worden gebruikt.
De centrale actie vereist een booleaanse eigenschap of een enum-eigenschap als C#-invoerargument.
De waarde van deze eigenschap bepaalt welke selector wordt gebruikt.
Dit gebeurt meestal via het gebruik van een enum. Vooral als er meer dan twee selectors nodig zijn, vormen enums de enige optie.
Voor gevallen met twee kierzers kunnen booleaanse waarden worden gebruikt.
Deze eigenschap, ook wel een beperkingsargument genoemd, moet een standaardwaarde hebben.
De centrale actie wordt gedeclareerd als een klassieke actie.
Merk op dat de eerste eigenschap (invoerargument) een enum is. Op basis van de waarde van die eigenschap wordt de juiste selector actief.
Opmerking
U kunt de argumenten op de gewenste manier ordenen door de waarde voor Order in te stellen naast het kenmerk 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
}
Aangepaste actieselectors met enums
In dit voorbeeld maakt u drie selectors. Een eenvoudige enum bepaalt telkens de juiste selector:
public enum SelectorChoice
{
Selector1,
Selector2,
Selector3
}
Selectors worden vertegenwoordigd door klassen.
Die klassen moeten de klasse ActionSelector<TBaseActionClass> overnemen.
Opmerking
TBaseActionClass is de naam van de basisactieklasse.
In de methode UseName() wordt de naam van de actieselector gedeclareerd. Deze wordt gebruikt als naam van de actie om de resources op te lossen.
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);
}
}
Opmerking
De klassen Selector mogen niet als acties worden gedeclareerd. De enige actie is de centrale. Selectors fungeren als filters.
In dit specifieke voorbeeld willen we slechts één van de argumenten weergeven, dus worden de andere eruit gefilterd. Hetzelfde doen we voor de klassen Selector2:
public class Selector2 : ActionSelector<CentralCustomAction>
{
public Selector2()
{
UseName("DisplayFullName");
Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector2);
ShowAll();
Hide(p => p.Age);
}
}
En Selector3:
public class Selector3 : ActionSelector<CentralCustomAction>
{
public Selector3()
{
UseName("DisplayFullDetails");
Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector3);
ShowAll();
}
}
De uiteindelijke uitvoering wordt bereikt via de methode Execute(ActionContext context) die zich in de centrale actie bevindt. Op basis van de selector worden de respectievelijke gefilterde waarden weergegeven.
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}";
}
}
Aangepaste actieselectors met booleaanse waarden
Het volgende is een voorbeeld waarbij booleaanse waarden worden gebruikt in plaats van enums.
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);
}
}
}
Beschrijvingen instellen voor aangepaste actieselectors
Gebruik de volgende indeling in het .resx-bestand van uw aangepaste module om een beschrijving en een samenvatting voor selectors te maken.
SelectorName_Description
SelectorName_Summary
Dit kan ook worden gedaan in de selector met de methoden WithDescription en WithSummary.
Belangrijk
.dll-bestanden die de aangepaste acties beschrijven, hun .dll-afhankelijkheden en het .cab-bestand dat alles bevat, moeten correct zijn ondertekend met een digitaal certificaat dat door uw organisatie wordt vertrouwd. Het certificaat moet ook op elke machine worden geïnstalleerd waarop een bureaubladstroom wordt opgesteld, gewijzigd of uitgevoerd, met aangepaste actieafhankelijkheden die aanwezig zijn onder de Vertrouwde basiscertificeringsinstanties.
Aangepaste module-id's
Elke module heeft een eigen ID (assemblynaam). Zorg er bij het maken van aangepaste modules voor dat u unieke module-id's instelt. Als u de assemblynaam van uw module wilt instellen, wijzigt u de eigenschap Assemblynaam in de sectie Algemeen van de eigenschappen van het C#-project.
Waarschuwing
Het opnemen van modules met dezelfde id in een stroom leidt tot conflicten
Naamconventies voor aangepaste modules
Om ervoor te zorgen dat de aangepaste modules leesbaar zijn via Power Automate voor bureaublad, moet de AssemblyName een bestandsnaam hebben die het onderstaande patroon volgt:
?*.Modules.?*
Modules.?*
Bijvoorbeeld Modules.ContosoActions.dll
De AssemblyTitle in de projectinstellingen specificeert de module-id. Het mag alleen alfanumerieke tekens en onderstrepingstekens bevatten en moet beginnen met een letter.
Ondertekenen van alle DLL's in de aangepaste module
Belangrijk
Het is verplicht om alle .dll bestanden die een aangepaste module (gegenereerde assembly en al zijn afhankelijkheden) bevatten, te laten ondertekenen met een vertrouwd certificaat
Om het maken van de aangepaste module te voltooien, moeten alle gegenereerde .dll bestanden, die te vinden zijn onder de map bin/release of bin/Debug van het project, worden ondertekend.
Onderteken alle .dll bestanden met een vertrouwd certificaat door de volgende opdracht (voor elk .dll bestand) uit te voeren in een Developer Command Prompt voor Visual Studio:
Onderteken alle .dll-bestanden met een vertrouwd certificaat door de volgende opdracht (voor elk .dll bestand) uit te voeren in een Developer Command Prompt voor 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
of door de volgende opdracht uit te voeren (door een Windows PowerShell Script .ps1 te maken) dat alle .dll-bestanden doorloopt en ze allemaal ondertekent met het meegeleverde certificaat:
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
}
Opmerking
Het digitale certificaat moet een exporteerbare persoonlijke sleutel en mogelijkheden voor codeondertekening hebben
Alles verpakken in een cabinetbestand
De .dll met de aangepaste acties en alle afhankelijkheden (.dll bestanden) moet worden verpakt in een cabinetbestand (.cab).
Opmerking
Volg bij het benoemen van het .cab-bestand de bestands- en mapnaamconventie voor het Windows-besturingssysteem. Gebruik geen spaties of speciale tekens zoals < > : " / \ | ? * .
Maak een Windows PowerShell-script (.ps1) met de volgende regels:
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
Dit Windows PowerShell-script kan vervolgens worden gebruikt voor het maken van het .cab-bestand door het aan te roepen in Windows PowerShell en het volgende op te geven:
- De map naar de .dll-bestanden die moeten worden gecomprimeerd.
- De doelmap om het gegenereerde .cab-bestand te plaatsen.
Roep het script aan met de volgende syntaxis:
.\{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
Voorbeeld:
.\makeCabFile.ps1 "C:\Users\Username\source\repos\MyCustomModule\bin\Release\net472" "C:\Users\Username\MyCustomActions" MyCustomActions.cab
Opmerking
- Zorg ervoor dat het daadwerkelijke .dll-bestand met aangepaste acties zich op het hoofdniveau van het beoogde pad bevindt wanneer u het .cab-bestand maakt en niet in een submap.
- Het .cab-bestand moet eveneens worden ondertekend. Niet-ondertekende .cab-bestanden en/of niet-ondertekende .dll's die ze bevatten, zijn niet bruikbaar in bureaubladstromen en resulteren in fouten tijdens de opname.