Opprette Power Automate for skrivebordshandlinger ved hjelp av Handlings-SDK

Artikkel
04/01/2024

Denne artikkelen beskriver hvordan du oppretter egendefinerte handlinger i Power Automate for skrivebordet.

Opprette egendefinerte handlinger

Viktig

Reserverte søkeord kan ikke brukes som handlingsnavn eller handlingsegenskaper. Bruk av reserverte nøkkelord som handlingsnavn eller handlingsegenskaper resulterer i feil virkemåte. Mer informasjon: Reserverte søkeord i skrivebordsflyt

Begynn ved å opprette en ny klassebibliotekprosjekt (.NET Framework). Velg .NET Framework versjon 4.7.2.

Slik oppretter du en handling i den egendefinerte modulen som opprettes:

Slett filen Class1.cs automatisk.
Opprett en ny klasse i prosjektet for å representere den egendefinerte handlingen, og gi den et distinkt navn.
Inkluder navneområdene Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK og Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes.
Alle klasser som representerer handlinger, må ha et [Action]-attributt over klassen.
Klassen må ha fellestilgang og arve fra ActionBase-klassen.

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 fleste handlinger kan ha parametere (inndata eller utdata). Inndata- og utdataparametere representeres av klassiske C#-egenskaper. Hver egenskap må ha et riktig C#-attributt, enten [InputArgument] eller [OutputArgument] for å diktere type og hvordan de presenteres i Power Automate for skrivebord. Inndataargumenter kan også ha standardverdier.

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

Legge til beskrivelser i egendefinerte handlinger

Legg til en beskrivelse og et egendefinert navn for modulene og handlingene, slik at RPA-utviklere vet hvordan de best kan bruke dem.

Power Automate for skrivebordsutforming viser egendefinerte navn og beskrivelser.

Du kan opprette en "Resources.resx"-fil i Egenskaper-mappen i modulprosjektet. Den nye RESX-filen må ha navnet "Resources.resx".

Formatet til beskrivelsene for Moduler og Handlinger må være som følger:

I henholdsvis Module_Description eller Handlingsbeskrivelse og Module_FriendlyName eller Action_FriendlyName i navnefeltet. Beskrivelsen i verdifeltet.

Vi anbefaler også at du oppgir beskrivelser og egendefinerte navn for parametere. Formatet skal være som følger: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Skjermbilde av Ressurser for en enkel handling

Tips

Det anbefales å angi hva det er du beskriver i kommentarfeltet (f.eks. modul, handling osv.)

Disse kan også angis med egenskapene FriendlyName og Description for attributtene [InputArgument], [OutputArgument] og [Action].

Her er et eksempel på en Resources.resx-fil for en tilpasset modul.

Skjermbilde av ressurser

En annen måte å raskt legge til egendefinerte navn og beskrivelser i handlinger og parametere på, er egenskapene FriendlyName og Description i [Handling] [InputArguement]- og [OutputArguement]-attributter.

Merk

Hvis du vil legge til et egendefinert navn og en beskrivelse i en modul, må du endre resx-filen eller legge til de respektive C#-attributtene.

Ressurslokalisering

Standardspråket for moduler i Power Automate for skrivebord antas å være engelsk.

Filen Resources.resx må være på engelsk.

Alle andre språk kan legges til med ekstra Ressurser.{locale}.resx-filer for lokalisering. For eksempel Resources.fr.resx.

Egendefinerte modulkategorier

Moduler kan inneholde kategorier og underkategorier for bedre handlingsorganisasjon.

Hvis du vil skille egendefinerte handlinger i kategorier, underkategorier, endrer du attributtet [Action] som står foran klassen som representerer den egendefinerte handlingen på følgende måte:

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

Merk

En Modul kan ha flere kategorier. Kategorier kan også bestå av underkategorier. Denne strukturen kan være ubestemt.

Order-egenskapen dikterer rekkefølgen som handlinger forhåndsvises i i utformingen.

Action1 tilhører kategorien TestCategory, og det er første handling i modulen (på denne måten forklarer du Ordre og kategori med et eksempel).

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

Betingede handlinger

Betingede handlinger er handlinger som returnerer enten True eller False. "Hvis filen finnes" er Power Automate for 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
    }
}

Legg merke til den boolske variabelen Resultat.

Handlingen Hvis filen finnes har ikke et utdataargument. Det den returnerer er sant eller usann, avhengig av hva den boolske variabelen Resultat inneholder.

Egendefinerte handlingsvelgere

Det finnes bestemte tilfeller der en egendefinert handling kan være nødvendig for å ha mer enn én variasjon.

Et eksempel er handlingen Start Excel fra standard handlingsbiblioteket.

Når du bruker velgeren "med et tomt dokument", starter flyten et tomt Excel-dokument, mens bruk av valget "og åpne følgende dokument" krever at filbanen til filen åpnes.

Skjermbilde av handlingsvelgerne Start Excel

De to handlingene nevnt ovenfor er to velgere av basishandlingen Start Excel.

Når du oppretter egendefinerte handlinger, trenger du ikke å skrive funksjonalitet på nytt.

Du kan opprette én enkelt basishandling, angi inndata- og utdataparametere, og deretter velge hva som skal være synlig i hver ramme ved å bruke handlingsvelgere.

Gjennom handlingsvelgere kan du legge til et abstraksjonsnivå over én enkelt handling, noe som gjør det mulig å hente spesifikk funksjonalitet fra én basishandling uten å måtte skrive kode på nytt for å danne en ny variasjon av den samme handlingen hver gang.

Tenk på velgere som valg, som filtrerer én enkelt handling og bare presenterer informasjonen som er nødvendig i henhold til de respektive velgerne.

Skjermbilde av handlingsvelgerdiagram

Hvis du vil opprette en ny handlingsvelger, oppretter du først en basishandling som skal brukes av velgerne.

Den sentrale handlingen krever en boolsk egenskap eller en opplistingsegenskap som et inndataargument for C#.

Verdien til denne egenskapen bestemmer hvilken velger som skal brukes.

Den vanligste måten er å bruke en opplisting. Spesielt når det er behov for flere enn to velgere, er opplistinger det eneste alternativet.

Boolske kan brukes for to velgersaker.

Denne egenskapen, også kalt et begrensningsargument, må ha en standardverdi.

Hovedhandlingen er deklarert som en klassisk handling.

Legg merke til at den første egenskapen (inndataargument) er en opplisting. Basert på egenskapens verdi blir riktig velger aktiv.

Merk

Hvis du vil at argumentene skal ordnes på riktig måte, angir du Ordre-verdien ved siden av attributtet 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
}

Egendefinerte handlingsvelgere som bruker opplistinger

I dette eksemplet oppretter du tre velgere. En enkel opplisting dikterer riktig velger hver gang:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Velgere representeres av klasser.

Disse klassene må arve ActionSelector<TBaseActionClass>-klassen.

Merk

TBaseActionClass er navnet på basishandlingsklassen.

I UseName()-metoden er navnet på handlingsvelgeren viktig. Dette brukes som et navn på handlingen for å løse ressursene.

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

Merk

Velger-klassene bør ikke brukes som handlinger. Den eneste handlingen er den sentrale. Velgere fungerer som filtre.

I dette bestemte eksemplet vil vi vise bare ett av argumentene, og dermed filtreres de andre ut. På samme måte for 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 utførelsen oppnås via Execute(ActionContext context) som finnes i den sentrale handlingen. Basert på velgeren vises de respektive verdiene filtrert.

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

Egendefinerte handlingsvelgere som bruker boolsk

Følgende er et eksempel på bruk av boolsk i stedet for opplistinger.

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

Angi beskrivelser for egendefinerte handlingsvelgere

Hvis du vil opprette en beskrivelse og et sammendrag for velgerne, bruker du følgende format i RESX-filen i den egendefinerte modulen.

SelectorName_Description
SelectorName_Summary

Dette kan også gjøres i velgeren med metodene WithDescription og WithSummary.

Viktig

DLL-filer som beskriver de egendefinerte handlingene, DLL-avhengighetene og CAB-filen som inneholder alt, må være riktig signert med et digitalt sertifikat som er klarert av organisasjonen. Sertifikatet må også installeres på hver maskin der en skrivebordsflyt med egendefinerte handlingsavhengigheter er skrevet, endret eller kjørt, som finnes under klarerte rotsertifiseringsinstanser.

Egendefinerte modul-IDer

Hver modul har sin egen ID (samlingsnavn). Når du oppretter egendefinerte moduler, kontrollerer du at du angir unike modul-ID-er. Hvis du vil angi samlingsnavnet for modulen, endrer du egenskapen Assembly name under Generelt-delen C#-prosjektegenskapene.

Advarsel!

Hvis du inkluderer moduler med samme ID i en flyt, vil det føre til konflikter

Egendefinerte modulnavnekonvensjoner

For at de egendefinerte modulene skal kunne leses via Power Automate for skrivebord, må AssemblyName ha et filnavn som følger mønsteret nedenfor:

?*.Modules.?*
Modules.?*

For eksempel Moduler.ContosoActions.dll

AssemblyTitle i prosjektinnstillingene angir modul-IDen. Den kan bare ha alfanumeriske tegn og understrekingstegn, og må begynne med en bokstav.

Logg alle DLL-er i den egendefinerte modulen

Viktig!

Det er obligatorisk at alle DLL-filene består av en tilpasset modul (generert samling og alle avhengigheter) som er undertegnet med et klarert sertifikat

For å fullføre opprettingen av den egendefinerte modulen må alle genererte DLL-filer, som du finner i bin/release- eller bin/Debug-mappen for prosjektet, undertegnes.

Logg alle DLL-filene med et klarert sertifikat ved å kjøre følgende kommando (for hver DLL-fil) i en utviklerledetekst for 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 å kjøre følgende kommando (ved å opprette et Windows PowerShell-skript .ps1) som går gjennom alle DLL-filene og logger hver av dem med det angitte sertifikatet:

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
}

Merk

Det digitale sertifikatet må ha en privatnøkkel og kodetegn som kan eksporteres

Pakke alt i en kabinettfil

DLL-filen som inneholder de egendefinerte handlingene og alle avhengighetene (DLL-filer), må pakkes i en CAB-fil.

Merk

Når du gir navn til CAB-filen, følger du filnavn- og mappenavnekonvensjonen for Windows-operativsystemet. Ikke bruk mellomrom eller spesialtegn, for eksempel < > : " / \ | ? * .

Opprett et Windows PowerShell-skript (PS1) som inneholder 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-skriptet kan deretter brukes til å opprette CAB-filen ved å starte den i Windows PowerShell og angi følgende:

Mappen til DLL-filene som skal komprimeres.
Målmappen for å plassere den genererte CAB-filen.

Start skriptet med 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

Merk

Kontroller at DLL-filen for de faktiske egendefinerte handlingene er i rotnivået til den målrettede banen når du oppretter CAB-filen, og ikke i en undermappe.
CAB-filen må også være signert. Usignerte CAB-filer og/eller usignerte DLL-filer i dem kan ikke brukes i flyter på skrivebordet, og det vil føre til feil under inkludering.

Neste trinn

Last opp egendefinerte handlinger

Del via

Opprette Power Automate for skrivebordshandlinger ved hjelp av Handlings-SDK

Opprette egendefinerte handlinger

Legge til beskrivelser i egendefinerte handlinger

Ressurslokalisering

Egendefinerte modulkategorier

Betingede handlinger

Egendefinerte handlingsvelgere

Egendefinerte handlingsvelgere som bruker opplistinger

Egendefinerte handlingsvelgere som bruker boolsk

Angi beskrivelser for egendefinerte handlingsvelgere

Egendefinerte modul-IDer

Egendefinerte modulnavnekonvensjoner

Logg alle DLL-er i den egendefinerte modulen

Pakke alt i en kabinettfil

Neste trinn

Tilbakemeldinger

Flere ressurser

Del via

Opprette Power Automate for skrivebordshandlinger ved hjelp av Handlings-SDK

Opprette egendefinerte handlinger

Legge til beskrivelser i egendefinerte handlinger

Ressurslokalisering

Egendefinerte modulkategorier

Betingede handlinger

Egendefinerte handlingsvelgere

Egendefinerte handlingsvelgere som bruker opplistinger

Egendefinerte handlingsvelgere som bruker boolsk

Angi beskrivelser for egendefinerte handlingsvelgere

Egendefinerte modul-IDer

Egendefinerte modulnavnekonvensjoner

Logg alle DLL-er i den egendefinerte modulen

Pakke alt i en kabinettfil

Neste trinn

Relatert informasjon

Tilbakemeldinger

Flere ressurser