Opret Power Automate til skrivebordshandlinger ved hjælp af Handlings-SDK
Denne artikel beskriver, hvordan du opretter tilpassede handlinger i Power Automate til desktop.
Oprette brugerdefinerede handlinger
Vigtigt
Reserverede søgeord kan ikke bruges som handlingsnavne og/eller handlingsegenskaber. Brug af reserverede søgeord som handlingsnavne og/eller handlingsegenskaber resulterer i fejlagtig adfærd. Flere oplysninger: Reserverede søgeord i desktop-flows
Begynd at oprette et nyt klassebiblioteksprojekt (.NET Framework). Vælg .NET Framework version 4.7.2.
Sådan oprettes en handling i det brugerdefinerede modul, der oprettes:
- Slet den automatisk genererede Class1.cs fil.
- Opret en ny klasse i projektet, der repræsenterer den brugerdefinerede handling, og giv den et tydeligt navn.
- Inkluder Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK og Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes namespaces.
- Alle klasser, der repræsenterer handlinger, skal have en [Handling]-attribut over din klasse.
- Klasserne skal have offentlig adgang og arve fra ActionBase-klasse.
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();
}
}
}
Fleste handlinger kan have parametre (Input eller Output). Input- og outputparametre repræsenteres ved klassisk C#-egenskaber.
De enkelte egenskaber skal have den rette C#-attribut [InputArgument] eller [OutputArgument] til at bestemme typen, og hvordan de vises på Power Automate til skrivebordet.
Inputargumenter kan også have standardværdier.
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}";
}
}
}
Tilføjelse af beskrivelser til brugerdefinerede handlinger
Tilføj en beskrivelse og et fuldt navn til modulerne og handlingerne, så RPA-udviklere ved, hvordan de bedst udnytter dem.
Power Automate til desktopdesigner viser fulde navne og beskrivelser.
Du kan oprette en "Resources.resx" fil i mappen Egenskaber i modulprojektet. Den nye ".resx"-fil skal have navnet "Resources.resx".
Beskrivelsesformatet for moduler og handlinger skal være følgende:
Henholdsvis "Module_Description" eller "Action_Description" og "Module_FriendlyName" eller "Action_FriendlyName" i navnefeltet. Beskrivelsen i værdifeltet.
Vi anbefaler også, at du angiver beskrivelser og venlige navne til parametre. Formatet skal være følgende: "Action_Parameter_Description", "Action_Parameter_FriendlyName".
Tip
Det anbefales, at du angiver, hvad det er, du beskriver i kommentarfeltet (f.eks. modul, handling osv.)
De kan også angives med egenskaberne FriendlyName og Beskrivelse for attributterne [InputArgument] [OutputArgument] og [Action].
Her er et eksempel på en Resources.resx-fil til et brugerdefineret modul.
En anden måde at føje fulde navne og beskrivelser til handlinger og parametre på er ved hjælp af egenskaberne FriendlyName og Beskrivelse i [Handling] [InputArguement] og [OutputArguement]-attributter.
Bemærk
Hvis du vil føje et fuldt navn og en beskrivelse til et modul, skal du ændre den pågældende .resx-fil eller tilføje de respektive C#-attributter.
Føje fejlhåndtering til brugerdefinerede handlinger
Hvis du vil definere brugerdefinerede undtagelser i din handling, skal du bruge [Throws("ActionError")] attributten over den brugerdefinerede handlingsklasse. Hver undtagelsessag, du vil definere, skal have sin egen attribut.
Brug følgende kode i catch-blokken:
throw new ActionException("ActionError", e.Message, e.InnerException);
Sørg for, at ActionException-navnet svarer til det navn, du har angivet i Throws.attributten. Brug throw new ActionException for hvert enkelt undtagelsestilfælde, og match det med det tilsvarende Throws-attributnavn. Alle undtagelser, der er defineret med attributten Throws, er synlige under fanen Håndtering af handlingsfejl i designeren.
Du kan finde et eksempel på dette i afsnittet Betingede handlinger .
Ressourcelokalisering
Standardsproget for moduler i Power Automate til desktop antages at være engelsk.
Filen Resources.resx skal være på engelsk.
Alle andre sprog kan tilføjes med ekstra ressourcer.{locale}.resx-filer, der skal lokaliseres. Eksempel Resources.fr.resx.
Brugerdefinerede modulkategorier
Moduler kan omfatte kategorier og underkategorier for at opnå en bedre handlingsorganisation.
Hvis du vil adskille brugerdefinerede handlinger i kategorier, skal du ændre attributten [Handling], der er før den klasse, der repræsenterer den brugerdefinerede handling, på følgende måde:
[Action(Category = "category.subcategory")]
Bemærk
Et modul kan have flere kategorier. På samme måde kan kategorier består af underkategorier. Denne struktur kan være ubestemt.
Egenskaben Ordre bestemmer den rækkefølge, som handlinger vises i i designeren.
Action1 hører til i kategorien "TestCategory", og det er den første handling i modulet (på denne måde forklarer du ordre og kategori med et eksempel).
[Action(Id = "Action1", Order = 1, Category = "TestCategory")]
Betingede handlinger
Betingede handlinger er handlinger, der enten returnerer "Sand" eller "Falsk". 'Hvis filen findes' er Power Automate til skrivebordshandling i standardbiblioteket et godt eksempel på en betinget handling.
Eksempel på Betinget handling:
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
}
}
Bemærk den booleske variabel Resultat.
Handlingen Hvis filen findes, har den ikke et outputargument. Det, der returneres, er enten sand eller falsk, afhængigt af hvad den booleske variabel Resultat indeholder.
Brugerdefinerede handlingsvælgere
Der er særlige tilfælde, hvor der kan kræves en brugerdefineret handling for at have mere end én handling.
Et eksempel er handlingen "Start Excel" fra standardbiblioteket for handlinger.
Hvis du bruger vælgeren "med et tomt dokument", startes der et tomt Excel-dokument i flowet, mens valg af "og åbn følgende dokument" kræver, at filens filsti åbnes.
De to handlinger, der er nævnt ovenfor, er to vælgere af basishandlingen "Start Excel".
Når du opretter brugerdefinerede handlinger, behøver du ikke at omskrive funktionaliteten.
Du kan oprette en enkelt "basishandling", angive input- og outputparametrene og derefter vælge, hvad der skal være synligt i hver enkelt handling ved hjælp af handlingsvælgere.
Via handlingsvælgere kan der tilføjes et niveau af indlæsning over en enkelt handling, hvilket gør det muligt at hente bestemte funktioner fra den enkelte "basishandling" uden at skulle skrive kode igen for at danne en ny enhed af samme handling hver gang.
Tænk på vælgere som valgmuligheder, filtrering af en enkelt handling og kun præsentation af de oplysninger, der kræves i henhold til de respektive vælgere.
Hvis du vil oprette en ny handlingsvælger, skal du først oprette en basishandling, der skal bruges af vælgerne.
Den centrale handling kræver enten en boolesk eller en optællingsegenskab som et input C#-argument.
Værdien af denne egenskab bestemmer, hvilken vælger der anvendes.
Den mest almindelige måde er at bruge en optælling på. Især når der er brug for mere end to vælgere, er optællinger den eneste indstilling.
I forbindelse med to vælgersager kan booleske adapter bruges.
Denne egenskab, som også kaldes et begrænsningsargument, skal have en standardværdi.
Den centrale handling anvendes som en klassisk handling.
Bemærk, at den første egenskab (inputargument) er en fasttekst. Afhængigt af værdien i den pågældende egenskab bliver den relevante vælger aktiv.
Bemærk
Hvis du vil have ordnet argumenterne på den ønskede måde, skal du angive værdien Ordre ud for attributten 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
}
Brugerdefinerede handlingsvælgere ved hjælp af fasttekst
I dette eksempel opretter du tre vælgere. En simpel optælling bestemmer den rette vælger hver gang:
public enum SelectorChoice
{
Selector1,
Selector2,
Selector3
}
Vælgere repræsenteres ved klasser.
Disse klasser skal arve ActionSelector<TBaseActionClass>-klassen.
Bemærk
TBaseActionClass er navnet på basishandlingsklassen.
I metoden UseName() er navnet på handlingsvælgeren angivet på en anden måde. Bruges som navnet på handlingen for at løse ressourcen.
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);
}
}
Bemærk
Klasserne Vælger skal ikke erklæres som handlinger. Den eneste handling er den centrale handling. Vælgere fungerer som filtre.
I dette specifikke eksempel vil vi kun vise ét af argumenterne, og derfor filtreres de andre ud. På samme måde gælder selector2:
public class Selector2 : ActionSelector<CentralCustomAction>
{
public Selector2()
{
UseName("DisplayFullName");
Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector2);
ShowAll();
Hide(p => p.Age);
}
}
Og Selector3-klasser:
public class Selector3 : ActionSelector<CentralCustomAction>
{
public Selector3()
{
UseName("DisplayFullDetails");
Prop(p => p.Selector).ShouldBe(SelectorChoice.Selector3);
ShowAll();
}
}
Den endelige udførelse udføres ved hjælp af metoden Execute(ActionContext context), der findes i den centrale handling. Afhængigt af vælgeren vises de respektive filtrerede værdier.
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}";
}
}
Brugerdefinerede handlingsvælgere bruger boolesk
Følgende er et eksempel, hvor der bruges boolesk i stedet for fasttekst.
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);
}
}
}
Angivelse af beskrivelser for brugerdefinerede handlingsvælgere
Hvis du vil oprette en beskrivelse og en oversigt for vælgere, skal du bruge følgende format i .resx-filen i det brugerdefinerede modul.
SelectorName_Description
SelectorName_Summary
Det kan du også gøre i vælgeren med metoderne WithDescription og WithSummary.
Vigtigt
.dll-filerne, der beskriver brugerdefinerede handlinger, deres afhængighed af .dll-filer og .cab-filerne, er korrekt signeret med et digitalt certifikat, der er tillid til af organisationen. Certifikatet skal også installeres på alle de computere, hvor et desktopflow med brugerdefinerede handlingsafhængigheder oprettes/ændres/køres, og som findes under nøglecenter, der er tillid til.
Brugerdefinerede modul-id'er
Hvert modul har sit eget id (assembly-navn). Når du opretter brugerdefinerede moduler, skal du sørge for at angive entydige modul-id'er. Hvis du vil angive assembly-navnet på modulet, skal du ændre egenskaben for Assembly-navn under afsnittet Generelt i egenskaberne for C#-projektet.
Advarsel!
Hvis der inkluderes moduler med samme id i et flow, opstår der konflikter
Brugerdefinerede regler for modulnavn
Hvis de brugerdefinerede moduler skal kunne læses gennem Power Automate til skrivebordet, skal AssemblyName have et filnavn, der følger nedenstående mønster:
?*.Modules.?*
Modules.?*
f.eks. Moduler.ContosoActions.dll
AssemblyTitle i projektindstillingerne angiver modul-id'et. Den må kun indeholde alfanumeriske tegn og understregningstegn, og den skal starte med et bogstav.
Signer alle DLL-adresser i det brugerdefinerede modul
Vigtigt!
Det er obligatorisk, at alle .dll-filerne udgør et brugerdefineret modul (genereret assembly og alle afhængigheder) signeret med et certifikat, der er tillid til
Hvis du vil afslutte oprettelsen af det brugerdefinerede modul, skal alle genererede .dll-filer, som findes under mappen bin/release eller bin/Debug i projektet, signeres.
Log på alle .dll-filerne ved hjælp af et certifikat, der er tillid til, ved at køre følgende kommando (for hver .dll-fil) i en kommandoprompt til udviklere i Visual Studio:
Log på alle .dll-filerne ved hjælp af et certifikat, der er tillid til, ved at køre følgende kommando (for hver .dll-fil) i en kommandoprompt til udviklere i 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
Eller ved at køre følgende kommando (ved at oprette et Windows PowerShell Script .ps1), der køres via alle .dll-filer, og signere dem alle med det medfølgende certifikat:
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
}
Bemærk
Digitale certifikater skal have en privat nøgle, der kan eksporteres og kodetegn, der kan eksporteres
Pakke alt i en kabinetfil
.dll, der indeholder de brugerdefinerede handlinger og alle afhængigheder (.dll-filer), skal pakkes i en kabinetfil (.cab).
Bemærk
Når du navngive .cab-filen, skal du følge navngivningskonventionen for filer og mapper for Windows-operativsystemet. Brug ikke mellemrum eller specialtegn som f.eks. < > : " / \ | ? * .
Opret et Windows PowerShell Script (.ps1), der indeholder følgende linjer:
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
Dette Windows PowerShell-script kan derefter bruges til at oprette .cab-filen ved at aktivere den i Windows PowerShell og angive følgende:
- Mappen til de .dll-filer, der skal komprimeres.
- Den destinationsmappe, der skal placere den oprettede .cab-fil.
Kald scriptet ved hjælp af følgende syntaks:
.\{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
Eksempel:
.\makeCabFile.ps1 "C:\Users\Username\source\repos\MyCustomModule\bin\Release\net472" "C:\Users\Username\MyCustomActions" MyCustomActions.cab
Bemærk
- Kontrollér, at den faktiske .dll-fil med brugerdefinerede handlinger findes på rodniveauet for målstien, når du opretter .cab-filen, og ikke i en undermappe.
- .cab-filen skal også være signeret. Ikke-signerede .cab-filer og/eller ikke-signerede .dll-filer, der findes i dem, kan ikke bruges i skrivebordsforløb, og de opstår fejl under inkluderingen.
Næste trin
Upload brugerdefinerede handlinger