Power Automate für Desktop-Aktionen mit dem Aktions-SDK erstellen
In diesem Artikel wird beschrieben, wie Sie benutzerdefinierte Aktionen in Power Automate für den Desktop erstellen.
Erstellen von benutzerdefinierten Aktionen
Wichtig
Reservierte Schlüsselwörter können nicht als Aktionsnamen und/oder Aktionseigenschaften verwendet werden. Die Verwendung reservierter Schlüsselwörter als Aktionsnamen und/oder Aktionseigenschaften führt zu fehlerhaftem Verhalten. Weitere Informationen: Reservierte Schlüsselwörter in Desktop-Flows
Erstellen Sie zunächst ein neues Klassenbibliotheks-Projekt (.NET Framework). Wählen Sie .NET Framework Version 4.7.2.
So bilden Sie eine Aktion im erstellten benutzerdefinierten Modul:
- Löschen Sie die automatisch generierte Datei Class1.cs.
- Erstellen Sie in Ihrem Projekt eine neue Klasse, um die benutzerdefinierte Aktion darzustellen, und geben Sie ihr einen eindeutigen Namen.
- Schließen Sie die Namespaces Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK und Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes ein.
- Alle Klassen, die Aktionen darstellen, sollten über Ihrer Klasse ein [Action]-Attribut haben.
- Die Klasse sollte öffentlichen Zugriff haben und von der ActionBase-Klasse erben.
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();
}
}
}
Die meisten Aktionen haben Parameter (Input oder Output). Eingabe- und Ausgabeparameter werden durch klassische C#-Eigenschaften dargestellt.
Jede Eigenschaft sollte entweder über ein entsprechendes C#-Attribut [InputArgument] oder [OutputArgument] verfügen, um ihren Typ und ihre Darstellung in Power Automate für Desktop festzulegen.
Eingabeargumente können auch Standardwerte haben.
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}";
}
}
}
Hinzufügen von Beschreibungen zu benutzerdefinierten Aktionen
Fügen Sie eine Beschreibung und einen benutzerfreundlichen Namen für die Module und Aktionen hinzu, damit RPA-Entwickler wissen, wie sie diese am besten nutzen können.
Power Automate für Desktop-Designer zeigt benutzerfreundliche Namen und Beschreibungen an.
Sie können eine „Resources.resx“-Datei im Eigenschaftenordner des Modulprojekts erstellen. Die neue „.resx“-Datei sollte „Resources.resx“ heißen.
Das Format der Beschreibungen für Module und Aktionen sollte wie folgt sein:
„Module_Description“ bzw. „Action_Description“ und „Module_FriendlyName“ bzw. „Action_FriendlyName“ im Namensfeld. Die Beschreibung im Wertfeld.
Wir empfehlen außerdem, Beschreibungen und benutzerfreundliche Anzeigenamen für Parameter bereitzustellen. Ihr Format sollte wie folgt sein: „Action_Parameter_Description“, „Action_Parameter_FriendlyName“.
Tipp
Es wird empfohlen, im Kommentarfeld anzugeben, was Sie beschreiben (z. B. Modul, Aktion usw.).
Diese können auch mit den Eigenschaften „FriendlyName“ und „Description“ festgelegt werden [InputArgument], [OutputArgument] und [Action] Attribute.
Hier ist ein Beispiel für eine Resources.resx-Datei für ein benutzerdefiniertes Modul.
Eine weitere Möglichkeit, schnell benutzerfreundliche Namen und Beschreibungen zu Aktionen und Parametern hinzuzufügen, sind die Eigenschaften „FriendlyName“ und „Description“ in den [Aktion], [InputArguement] und [OutputArguement] Attributen.
Anmerkung
Um einem Modul einen Anzeigenamen und eine Beschreibung hinzuzufügen, müssen Sie die entsprechende .resx-Datei ändern oder die entsprechenden C#-Attribute hinzufügen.
Lokalisierung von Ressourcen
Bei der Standardsprache für Module in Power Automate für Desktop wird davon ausgegangen, dass es sich um Englisch handelt.
Die Resources.resx-Datei sollte auf Englisch sein.
Alle anderen Sprachen können mit zusätzlichen Resources.{locale}.resx-Dateien zur Lokalisierung hinzugefügt werden. Beispiel: Resources.fr.resx.
Benutzerdefinierte Modulkategorien
Module können Kategorien und Unterkategorien zur besseren Organisation von Aktionen enthalten.
Um benutzerdefinierte Aktionen in Kategorien und Unterkategorien zu unterteilen, ändern Sie das Attribut [Action], das der Klasse vorangeht, die die benutzerdefinierte Aktion darstellt, wie folgt:
[Action(Category = "category.subcategory")]
Anmerkung
Ein Modul kann mehrere Kategorien haben. Ebenso können Kategorien aus Unterkategorien bestehen. Diese Struktur kann unbestimmt sein.
Die Order-Eigenschaft bestimmt die Reihenfolge, in der Aktionen im Designer in der Vorschauversion angezeigt werden.
Action1 gehört in die Kategorie „TestCategory“ und ist die erste Aktion des Moduls (auf diese Weise erklären Sie Reihenfolge und Kategorie anhand eines Beispiels).
[Action(Id = "Action1", Order = 1, Category = "TestCategory")]
Bedingte Aktionen
Bedingte Aktionen sind Aktionen, die entweder „True“ oder „False“ zurückgeben. „Wenn Datei vorhanden ist“ Power Automate für Desktop-Aktion der Standardbibliothek ist ein gutes Beispiel für eine bedingte Aktion.
Beispiel für eine bedingte Aktion:
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
}
}
Beachten Sie die boolesche Variable Result.
Die Aktion Wenn Datei existiert hat kein Ausgabeargument. Was zurückgegeben wird, ist entweder wahr oder falsch, je nachdem, was die boolesche Variable Result enthält.
Benutzerdefinierte Aktionsselektoren
In bestimmten Fällen kann es erforderlich sein, dass eine benutzerdefinierte Aktion mehr als eine Variante aufweist.
Ein Beispiel ist die Aktion „Excel starten“ aus der Standard-Aktionsbibliothek.
Bei Verwendung der Auswahl „Mit leerem Dokument“ startet der Flow ein leeres Excel-Dokument, während bei Verwendung der Auswahl „Und folgendes Dokument öffnen“ der Dateipfad der zu öffnenden Datei angegeben werden muss.
Die beiden oben genannten Aktionen sind zwei Auswahlhilfen der Basisaktion „Excel starten“.
Beim Erstellen benutzerdefinierter Aktionen müssen Sie die Funktionalität nicht neu schreiben.
Sie können eine einzelne „Basis“-Aktion erstellen, deren Eingabe- und Ausgabeparameter festlegen und dann mithilfe von Aktionsselektoren auswählen, was in jeder Variante sichtbar sein soll.
Durch Aktionsselektoren kann einer einzelnen Aktion eine Abstraktionsebene hinzugefügt werden, die den Abruf spezifischer Funktionen aus der einzelnen „Basis“-Aktion ermöglicht, ohne dass Code jedes Mal neu geschrieben werden muss, um eine neue Variante derselben Aktion zu erstellen.
Stellen Sie sich Auswahlhilfen als Auswahlmöglichkeiten vor, die eine einzelne Aktion filtern und nur die Informationen anzeigen, die für die jeweiligen Auswahlhilfen erforderlich sind.
Um einen neuen Aktionsselektor zu bilden, erstellen Sie zunächst eine Basisaktion, die von den Auswahlhilfen verwendet werden soll.
Die zentrale Aktion erfordert entweder eine boolesche oder eine Enumerationseigenschaft als C#-Eingabeargument.
Der Wert dieser Eigenschaft bestimmt, welche Auswahlhilfe verwendet wird.
Die gebräuchlichste Methode ist die Verwendung einer Enumeration. Insbesondere wenn mehr als zwei Auswahlhilfen benötigt werden, sind Aufzählungen die einzige Option.
Für zwei Selektorfälle können boolesche Werte verwendet werden.
Diese Eigenschaft, auch Einschränkungsargument genannt, muss einen Standardwert haben.
Die zentrale Aktion wird als klassische Aktion deklariert.
Beachten Sie, dass die erste Eigenschaft (Eingabeargument) eine Aufzählung ist. Basierend auf dem Wert dieser Eigenschaft wird die entsprechende Auswahlhilfe aktiv.
Anmerkung
Um die Argumente in der gewünschten Weise zu ordnen, legen Sie den Order-Wert neben dem InputArgument-Attribut fest.
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
}
Benutzerdefinierte Aktionsselektoren mit Aufzählungen
In diesem Beispiel erstellen Sie drei Auswahlhilfen. Eine einfache Aufzählung gibt jedes Mal die passende Auswahlhilfe vor:
public enum SelectorChoice
{
Selector1,
Selector2,
Selector3
}
Auswahlhilfen werden durch Klassen repräsentiert.
Diese Klassen müssen von der ActionSelector<TBaseActionClass>-Klasse erben.
Anmerkung
TBaseActionClass ist der Name der Basisaktionsklasse.
In der Methode UseName() wird der Name des Aktionsselektors deklariert. Dies wird als Name der Aktion zum Auflösen der Ressourcen verwendet.
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);
}
}
Anmerkung
Die Auswahlhilfe Klassen sollten nicht als Aktionen deklariert werden. Die einzige Aktion ist die zentrale. Auswahlhilfen fungieren als Filter.
In diesem speziellen Beispiel möchten wir nur eines der Argumente anzeigen, daher werden die anderen herausgefiltert. Ähnliches gilt für Auswahlhilfe2:
public class Selector2 : ActionSelector<CentralCustomAction>
{
public Selector2()
{
UseName("DisplayFullName");
Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector2);
ShowAll();
Hide(p => p.Age);
}
}
Und Auswahlhilfe3 Klassen:
public class Selector3 : ActionSelector<CentralCustomAction>
{
public Selector3()
{
UseName("DisplayFullDetails");
Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector3);
ShowAll();
}
}
Die endgültige Ausführung wird durch erreicht Execute(ActionContext-Kontext) Methode, die in der zentralen Aktion liegt. Basierend auf der Auswahlhilfe werden die jeweiligen gefilterten Werte angezeigt.
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}";
}
}
Benutzerdefinierte Aktionsselektoren mit booleschen Werten
Das Folgende ist ein Beispiel, bei dem boolesche Werte anstelle von Aufzählungen verwendet werden.
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);
}
}
}
Einstellungsbeschreibungen für benutzerdefinierte Aktionsselektoren
Um eine Beschreibung und eine Zusammenfassung für Auswahlhilfen zu erstellen, verwenden Sie das folgende Format in der .resx-Datei Ihres benutzerdefinierten Moduls.
SelectorName_Description
SelectorName_Summary
Dies kann auch in der Auswahlhilfe mit den Methoden WithDescription und WithSummary erfolgen.
Wichtig
DLL-Dateien, die die benutzerdefinierten Aktionen beschreiben, ihre DLL-Abhängigkeiten und die CAB-Datei, die alles enthält, sollten ordnungsgemäß mit einem digitalen Zertifikat signiert sein, dem Ihr Unternehmen vertraut. Das Zertifikat sollte auch auf jedem Computer installiert werden, auf dem ein Desktop-Flow mit benutzerdefinierten Aktionsabhängigkeiten verfasst/geändert/ausgeführt wird, der unter den vertrauenswürdigen Stammzertifizierungsstellen vorhanden sind.
Benutzerdefinierte Modul-IDs
Jedes Modul hat seine eigene ID (Assembly-Name). Stellen Sie beim Erstellen benutzerdefinierter Module sicher, dass Sie eindeutige Modul-IDs festlegen. Um den Assembly-Namen Ihres Moduls festzulegen, ändern Sie die Eigenschaft Assembly-Name im Abschnitt „Allgemein“ der Eigenschaften des C#-Projekts.
Warnung
Das Einschließen von Modulen mit derselben ID in einen Flow führt zu Konflikten
Konventionen für benutzerdefinierte Modulnamen
Damit die benutzerdefinierten Module über Power Automate für Desktop lesbar sind, muss der AssemblyName einen Dateinamen haben, der dem folgenden Muster folgt:
?*.Modules.?*
Modules.?*
Beispiel: Modules.ContosoActions.dll
Der AssemblyTitle in den Projekteinstellungen gibt die Modul-ID an. Es darf nur alphanumerische Zeichen und Unterstriche enthalten und muss mit einem Buchstaben beginnen.
Alle DLLs im benutzerdefinierten Modul signieren
Wichtig
Es ist zwingend erforderlich, dass alle DLL-Dateien, aus denen ein benutzerdefiniertes Modul besteht (generierte Assembly und alle ihre Abhängigkeiten), mit einem vertrauenswürdigen Zertifikat signiert sind
Um die Erstellung des benutzerdefinierten Moduls abzuschließen, müssen alle generierten DLL-Dateien, die sich im Ordner „bin/release“ oder „bin/Debug“ des Projekts befinden, signiert werden.
Signieren Sie alle DLL-Dateien mit einem vertrauenswürdigen Zertifikat, indem Sie den folgenden Befehl (für jede DLL-Datei) in einer Entwickler-Eingabeaufforderung für Visual Studio ausführen:
Signieren Sie alle DLL-Dateien mit einem vertrauenswürdigen Zertifikat, indem Sie den folgenden Befehl (für jede DLL-Datei) in einer Entwickler-Eingabeaufforderung für Visual Studio ausführen:
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
Oder indem Sie den folgenden Befehl ausführen (durch Erstellen eines Windows PowerShell-Skripts .ps1), das alle DLL-Dateien durchläuft und jede einzelne mit dem bereitgestellten Zertifikat signiert:
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
}
Anmerkung
Das digitale Zertifikat muss über einen exportierbaren privaten Schlüssel und die Fähigkeit zur Code-Signierung verfügen
Alles in eine CAB-Datei packen
Die DLL mit den benutzerdefinierten Aktionen und allen zugehörigen Abhängigkeiten (DLL-Dateien) muss in einer CAB-Datei (.cab) gepackt werden.
Anmerkung
Befolgen Sie beim Benennen der CAB-Datei die Datei- und Ordnerbenennungskonvention für das Windows-Betriebssystem. Verwenden Sie keine Leerzeichen oder Sonderzeichen wie z. B. < > : " / \ | ? * .
Erstellen Sie ein Windows PowerShell-Skript (.ps1), das die folgenden Zeilen enthält:
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
Dieses Windows PowerShell-Skript kann dann zum Erstellen der CAB-Datei verwendet werden, indem es in Windows PowerShell aufgerufen und Folgendes bereitgestellt wird:
- Das Verzeichnis der zu komprimierenden DLL-Dateien.
- Das Zielverzeichnis zum Platzieren der generierten CAB-Datei.
Rufen Sie das Skript mithilfe der folgenden Syntax auf:
.\{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
Beispiel:
.\makeCabFile.ps1 "C:\Users\Username\source\repos\MyCustomModule\bin\Release\net472" "C:\Users\Username\MyCustomActions" MyCustomActions.cab
Anmerkung
- Stellen Sie sicher, dass sich die eigentliche DLL-Datei mit benutzerdefinierten Aktionen beim Erstellen der CAB-Datei auf der Stammebene des Zielpfads und nicht in einem Unterordner befindet.
- Die CAB-Datei muss auch signiert sein. Nicht signierte CAB-Dateien und/oder darin enthaltene nicht signierte DLLs können in Desktop-Flows nicht verwendet werden und führen beim Einbinden zu Fehlern.
Nächste Schritte,
Benutzerdefinierte Aktionen hochladen