Eylemler SDK'sını kullanarak masaüstü için Power Automate eylemleri oluşturma

Bu makalede Power Automate masaüstünde özel eylemlerin nasıl oluşturulacağı açıklanmaktadır.

Özel eylemler oluşturma

Yeni bir Sınıf Kitaplığı (.NET Framework) projesi oluşturarak başlayın. .NET Framework sürüm 4.7.2'yi seçin.

Oluşturulan özel modülde bir eylem oluşturmak için:

• Otomatik olarak oluşturulmuş Class1.cs dosyasını silin.
• Özel eylemi göstermek için projenizin içinde yeni bir sınıf oluşturun ve buna farklı bir ad verin.
• Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK ve Microsoft.PowerPlatform.PowerAutomate.Desktop.Actions.SDK.Attributes ad alanlarını ekleyin.
• Eylemleri temsil eden tüm sınıfların sınıfınız üzerinde bir [Action] özniteliği olmalıdır.
• Sınıf ortak erişime sahip olmalı ve ActionBase sınıfından devralmalıdır.

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

Çoğu eylem parametrelere (Giriş veya Çıkış) sahiptir Giriş ve Çıkış parametreleri klasik C# özellikleri tarafından temsil edilir. Her özelliğin, kendi türünü ve bunun masaüstü için Power Automate'te nasıl sunulduğunu belirtmek için uygun bir C# özniteliği (ya [InputArgument] ya da [OutputArgument]) olmalıdır. Giriş bağımsız değişkenleri varsayılan değerlere de sahip olabilir.

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

Özel eylemlere açıklama ekleme

Modüller ve eylemler için birer açıklama ve kolay ad ekleyin, böylece RPA geliştiricileri bunlardan nasıl en iyi şekilde yararlanabileceğini anlayabilir.

Masaüstü için Power Automate tasarımcısı, kolay adları ve açıklamaları gösterir.

Modül projesinin Properties klasöründe bir "Resources.resx" dosyası oluşturabilirsiniz. Yeni ".resx" dosyası "Resources.resx" olarak adlandırılmalıdır.

Modüllerin ve Eylemlerin açıklamalarının biçimi aşağıdaki gibi olmalıdır:

Ad alanında sırasıyla "Module_Description" veya "Action_Description" ve "Module_FriendlyName" veya "Action_FriendlyName". Değer alanındaki açıklama.

Ayrıca parametreler için açıklamalar ve kolay adlar vermenizi de öneririz. Bunların biçimi şöyle olmalıdır: "Action_Parameter_Description", "Action_Parameter_FriendlyName".

Bunlar [InputArgument], [OutputArgument] ve [Action] özniteliklerinin FriendlyName ve Description özellikleriyle de ayarlanabilir.

İşte özel bir modül için Resources.resx dosyası örneği.

Eylemlere ve parametrelere hızlı şekilde kolay adlar ve açıklamalar eklemenin başka bir yolu da [Action], [InputArguement] ve [OutputArguement] özniteliklerindeki FriendlyName ve Description özelliklerini kullanmaktır.

Özel eylemlere hata işleme ekleme

Eyleminizde özel istisnalar tanımlamak için özel eylem sınıfının üstündeki [Throws("ActionError")] niteliğini kullanın. Tanımlamak istediğiniz her özel durum durumunun kendi özniteliği olmalıdır.

Catch bloğunda aşağıdaki kodu kullanın:

throw new ActionException("ActionError", e.Message, e.InnerException);

ActionException adının Throws öznitelik içinde belirttiğiniz adla eşleştiğinden emin olun. Her özel durum için throw new ActionException kullanın ve karşılık gelen Throws öznitelik adıyla eşleştirin. Throws öznitelikle tanımlanan tüm özel durumlar, tasarımcının eylem hatası işleme sekmesinde görünür.

Bunun bir örneğini Koşullu eylemler bölümünde bulabilirsiniz.

Kaynaklar yerelleştirmesi

Masaüstü için Power Automate'teki modüllerin varsayılan dilinin İngilizce olduğu varsayılır.

Resources.resx dosyası İngilizce olmalıdır.

Diğer tüm diller yerelleştirme için ek Resources.{locale}.resx dosyalarıyla eklenebilir. Örneğin, Resources.fr.resx.

Özel modül kategorileri

Modüller, eylemlerin daha iyi organize edilmesi için kategorileri ve alt kategorileri içerebilir.

Özel eylemleri kategorilere ve alt kategorilere ayırmak için, özel eylemi temsil eden sınıftan önce olan [Action] özniteliğini aşağıdaki şekilde değiştirin:

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

Order özelliği, eylemlerin tasarımcıda önizlenme sırasını belirler.

Action1, "TestCategory" kategorisine aittir ve bu, modülün ilk eylemidir (böylece Sıra ve kategoriyi bir örnekle açıklarsınız).

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

Koşul eylemleri

Koşullu eylemler, "true" veya "false" değerini döndüren eylemlerdir. Standart kitaplığın masaüstü için Power Automate eylemi olan "Dosya varsa", koşullu eylem için iyi bir örnektir.

Koşullu eylem örneği:

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

Sonuç Boolean değişkenine dikkat edin.

Dosya varsa eyleminde çıkış bağımsız değişkeni yoktur. Sonuç Boolean değişkeninin değerine bağlı olarak true veya false döndürür.

Özel eylem seçiciler

Bir özel eylemin birden çok varyasyona sahip olması gerekebilecek belirli durumlar vardır.

Standart eylemler kitaplığındaki"Excel'i Başlat" eylemi buna bir örnektir.

"Boş belgeyle" seçicisini kullanarak akış, boş bir Excel belgesi başlatır; "ve şu belgeyi açın" seçiminin kullanımı ise dosyanın açılması için dosya yolunu gerektirir.

Yukarıda bahsedilen iki eylem, "Excel'i Başlat" temel eyleminin iki seçicisiyle aynıdır.

Özel eylemler oluştururken işlevselliği yeniden yazmanız gerekmez.

Tek bir "temel" eylem oluşturabilir, giriş ve çıkış parametrelerini belirleyebilir ve ardından eylem seçiciler aracılığıyla her bir özellikte nelerin görünür olacağını seçebilirsiniz.

Eylem seçiciler yoluyla tek bir eylem üzerine bir soyutlama düzeyi eklenebilir, böylece aynı eylemin her seferinde yeni bir varyasyonunu oluşturmak için kodu yeniden yazmak zorunda kalmadan tek bir "temel" eylemden belirli bir işlevsellik alınabilir.

Seçicileri, tek bir eylemi filtreleyen ve yalnızca ilgili seçicilere göre gereken bilgileri sunan seçimler olarak düşünebilirsiniz.

Yeni bir eylem seçici oluşturmak için, önce seçiciler tarafından kullanılacak bir temel eylem oluşturun.

Merkezi eylem, giriş C# bağımsız değişkeni olarak bir Boolean veya sabit listesi özelliği gerektirir.

Bu özelliğin değeri, hangi seçicinin kullanılacağını belirler.

En yaygın yol bir sabit listesi kullanmaktır. Özellikle ikiden fazla seçici gerekiyorsa, sabit listeler tek seçenektir.

İki seçici bulunan durumlar için Boolean kullanılabilir.

Kısıtlama bağımsız değişkeni olarak da bilinen bu özelliğin varsayılan bir değeri olmalıdır.

Merkezi eylem klasik eylem olarak bildirilir.

İlk özelliğin (giriş bağımsız değişkeni) bir sabit listesi olduğunu unutmayın. Bu özelliğin değerine bağlı olarak, uygun seçici etkin duruma gelir.

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
}

Sabit listeleri kullanılan özel eylem seçiciler

Bu örnekte üç seçici oluşturursunuz. Basit bir sabit listesi her seferinde uygun seçiciyi belirler:

public enum SelectorChoice
{
    Selector1,
    Selector2,
    Selector3
}

Seçiciler sınıflarla gösterilir.

Bu sınıfların ActionSelector<TBaseActionClass> sınıfını devralması gerekir.

UseName() yönteminde eylem seçicinin adı bildirilir. Bu, kaynakları çözecek eylemin adı olarak kullanılır.

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

Bu örnekte, bağımsız değişkenlerden yalnızca birini görüntülemek istiyoruz, bu nedenle diğerlerine filtre uygulanır. Selector2 için de benzer şekilde:

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

Ve Selector3 sınıfları:

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

Son yürütme, merkezi eylemde yer alan Execute(ActionContext context) yöntemi aracılığıyla elde edilir. Seçiciye göre, filtre uygulanan ilgili değerler görüntülenir.

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

Boolean kullanılan özel eylem seçiciler

Aşağıdaki örnek, sabit listeleri yerine Boolean kullanılan bir örnektir.

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

Özel eylem seçiciler için açıklama ayarlama

Seçiciler için açıklama ve özet oluşturmak üzere özel modülünüzün .resx dosyasında aşağıdaki biçimi kullanın.

SelectorName_Description
SelectorName_Summary

Bu, seçicide WithDescription ve WithSummary yöntemleriyle de yapılabilir.

Özel modül kimlikleri

Her modülün kendi kimliği (derleme adı) vardır. Özel modüller oluştururken, benzersiz modül kimlikleri ayarladığınızdan emin olun. Modülünüzün derleme adını ayarlamak için C# projesinin özelliklerinin Genel bölümü altında Derleme adı özelliğini değiştirin.

Özel modül adlandırma kuralları

Özel modüllerin masaüstü için Power Automate aracılığıyla okunabilir olması için AssemblyName, aşağıdaki deseni izleyen bir dosya adına sahip olmalıdır:

?*.Modules.?*
Modules.?*

Örneğin, Modules.ContosoActions.dll

Proje ayarlarındaki AssemblyTitle, modül kimliğini belirtir. Yalnızca alfasayısal karakterler ve alt çizgi içerebilir ve bir harfle başlaması gerekir.

Özel modül içindeki tüm DLL'leri imzalama

Özel modülün oluşturulmasını son haline getirmek için projenin bin/release veya bin/Debug klasöründe bulunabilecek oluşturulan tüm .dll dosyalarının imzalanması gerekir.

Visual Studio için Geliştirici Komut İsteminde aşağıdaki komutu (her .dll dosyası için) çalıştırarak güvenilen bir sertifika kullanarak tüm .dll dosyalarını imzalayın:

Visual Studio için Geliştirici Komut İsteminde aşağıdaki komutu (her .dll için) çalıştırarak güvenilen bir sertifika kullanarak tüm .dll dosyalarını imzalayın:

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

Veya aşağıdaki komutu (bir Windows PowerShell Komut Dosyası .ps1 oluşturarak) çalıştırıp tüm .dll dosyaları yineleyen ve her birini sağlanan sertifikayla imzalayan:

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
}

Dolap dosyasında her şeyi paketleme

Özel eylemleri ve tüm bağımlılıklarını (.dll dosyaları) içeren .dll, dolap dosyasında (.cab) paketlenmelidir.

Aşağıdaki satırları içeren bir Windows PowerShell betiği (.ps1) oluşturun:

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

Bu Windows PowerShell betiği, Windows PowerShell'de çağırarak ve şunları sağlayarak .cab dosyasının oluşturulması için kullanılabilir:

• Sıkıştırılacak .dll dosyalarının dizini.
• Oluşturulan .cab dosyasının yerleştirileceği hedef dizin.

Aşağıdaki sözdizimini kullanarak komut dosyasını çağırın:

.\{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

Örnek:

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

Sonraki adımlar

Özel eylemleri yükle

İlgili bilgiler

• Varlık kitaplığı
• Özel eylemleri kullanma
• Özel eylemler