Benutzerdefinierte Aufgaben

[ChristianKienzl]

So erstellen Sie eine benutzerdefinierte Friends-Aufgabe.

Geschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contents

Schnellstart

Wir habenAufgabenvorlageDadurch wird eine einsatzbereite Visual Studio-Lösung erstellt. Sie kann in ein NuGet-Paket gepackt und auf Frends hochgeladen werden. Sie können Ihre bevorzugte C#-IDE verwenden, z. B. Visual Studio, VS Code oder Rider.

Erstellen eines Friends-Aufgabenpakets

Frends unterstützt Sie vollständig beim Erstellen eigener Task-Pakete. Dazu müssen Sie eine .NET-Klassenbibliothek erstellen, die dann in eine NuGet-Paketdatei gepackt und über die Tasks-Seite in Frends hochgeladen wird.

Um eine Frends-Aufgabe zu erstellen, müssen Sie zuerst eine .NET-Klassenbibliothek erstellen, vorzugsweise für mehrere Zielgruppen geeignet.NET Standard 2.0 und .NET Framework 4.7.1, damit sie sowohl auf Windows- als auch auf Linux-basierten Agenten funktioniert.

Frends unterstützt Klassenbibliotheken von .NET Standard 2.0 und .NET Framework 4.7.1 ab Version 5.0. Frühere Frends-Versionen unterstützten nur Bibliotheken für .NET Framework bis 4.5.2. Wenn Sie also ältere Frends-Versionen ausführen möchten, müssen Sie .NET 4.5.2 als Ziel verwenden.

Beachten Sie beim Erstellen der Klassenbibliothek, dass die Aufgabe als öffentliche statische Methode mit Rückgabewert implementiert werden sollte. Nicht statische Methoden oder Methoden ohne Rückgabewert (void) können nicht als Aufgaben verwendet werden. Die Methoden können nicht überladen werden, d. h. Frends.TaskLibrary.CreateFile(string filePath) und Frends.TaskLibrary.CreateFile(string filePath, bool overwrite) sind nicht möglich.

Verpacken der neu erstellten Aufgaben.

Task-Bibliotheken werden als NuGet-Pakete (.nupkg) verteilt. Der Assemblyname und die Paket-ID müssen identisch sein, z. B. Frends.TaskTemplate.dll und Frends.TaskTemplate.1.0.0.0.nupkg.

Normalerweise kann die Aufgabe mit dem Befehl gepackt werdenDotnet-Paketaber manchmal, normalerweise beim Arbeiten mit Legacy-Code, müssen Sie zum Packen der Aufgabe nuget.exe- und .nuspec-Dateien verwenden.

Aufgabenparameter

Alle für die Methode angegebenen Parameter werden als Task-Parameter verwendet. Wenn der Parameter vom Klassentyp ist, wird er als Struktur initialisiert.

Zum Beispiel:

mit System.ComponentModel;

Namespace Frends.TaskLibrary
{ 
/// <Zusammenfassung>
/// Dateiaktionstyp (nichts/löschen/umbenennen/löschen)
/// </summary>
öffentliche Aufzählung ActionType
    {
/// <Zusammenfassung>
/// Es wird nichts mit der Datei gemacht
/// </summary>
Nichts,

/// <Zusammenfassung>
/// Datei wird gelöscht
/// </summary>
Löschen,
/// <Zusammenfassung>
/// Datei wird umbenannt
/// </summary>
Umbenennen,

/// <Zusammenfassung>
/// Datei wird verschoben
/// </summary>
Bewegen
    }

/// <Zusammenfassung>
/// Dateiklasse
/// </summary>
öffentliche Klasse Datei
    {
/// <Zusammenfassung>
/// Dateipfad
/// </summary>
[Standardwert("\"C:\\Temp\\meineDatei.json\"")]
öffentlicher String-Pfad { abrufen; festlegen; }

/// <Zusammenfassung>
/// Maximale Größe der Datei
/// </summary>
[Standardwert("0")]
öffentliche int MaxSize { abrufen; festlegen; }


/// <Zusammenfassung>
/// Passwort zum Entsperren der Datei
/// </summary>
[PasswortEigenschaftstext]
öffentliche Zeichenfolge Passwort { abrufen; festlegen; }
    }

/// <Zusammenfassung>
/// Die FileAction-Klasse definiert, was mit der Datei geschieht
/// </summary>
öffentliche Klasse „FileAction“
    {
/// <Zusammenfassung>
/// Mit der Datei auszuführende Aktion
/// </summary>
öffentlicher ActionType Action { abrufen; festlegen; }

/// <Zusammenfassung>
/// Wenn ActionType Move oder Rename ist, dann ist To der zu verwendende Pfad.
/// </summary>
[Standardwert("\"\"")]
öffentliche Zeichenfolge Zum { abrufen; festlegen; }
    }

öffentliche statische Klassendateien
    {
/// <Zusammenfassung>
/// Die Aufgabe „DoFileAction“ führt die gewünschte Aktion mit der Datei aus
/// </summary>
/// <param name="file">Zu verarbeitende Datei</param>
/// <param name="action">Auszuführende Aktion</param>
/// <returns>Gibt Informationen zurück, ob die Aufgabe erfolgreich war</returns>
öffentliche statische Zeichenfolge DoFileAction(Datei, FileAction-Aktion)
        {
// TODO: Logik ändern
return $"Eingabewerte. Pfad: '{file.Path}', Max. Größe: '{file.MaxSize}', Aktion: '{action.Action}', An: '{action.To}'";
        }
    }
}

Bei einer komplexen oder großen Parameterstruktur können Sie benutzerdefinierte Attribute aus der ComponentModel-Bibliothek verwenden. Verwenden Sie Assets inSystem.KomponentenmodellUndSystem.ComponentModel.DataAnnotationsNamespaces, um anzugeben, wie die Parameter in der Benutzeroberfläche angezeigt werden. Für .NET Standard 2.0-Aufgabenbibliotheken sind die Attribute verfügbar überSystem.ComponentModel.AnnotationsNuGet-Paket.

Benutzerdefinierte Attribute von System.ComponentModel.DataAnnotations werden ab Frends Version 4.5.6 unterstützt.

Standardwert: DefaultValueAttribute

Aufgabenparameter können denStandardwertattributum einen Standardwert bereitzustellen, der im Editor angezeigt wird, denken Sie daran, dass die Parameter Ausdrücke im Editor sind und Standardwerte als solche bereitgestellt werden müssen, z. B. „true“ für einen Booleschen Wert, „\"C:\Temp\\"" für eine Zeichenfolge, die einen Dateipfad enthält.

Vertrauliche Informationen, die nicht protokolliert werden sollen: PasswordPropertyTextAttribute

Wenn ein Parameter nicht protokolliert werden soll,PasswordPropertyTextAttributehinzugefügt werden soll. Der Wert des Parameters wird ersetzt durch<< Geheimnis >>im Protokoll. Parameter können eine komplexere hierarchische Struktur haben. Wir empfehlen, höchstens zwei Hierarchieebenen zu verwenden.

Optionale Eingaben: UIHintAttribute

[UIHint(nameof(Eigenschaft),"", Bedingungen: Objekt[]]

Zeigen oder verbergen Sie Editoreingaben basierend auf dem Wert anderer Eingaben.

Beispiel:

öffentliches bool Umbenennen { abrufen; festlegen; }
[UIHint(nameof(Umbenennen),"", true)]
öffentliche Zeichenfolge NeuerDateiname { abrufen; festlegen; }

Das Feld NewFileName ist nur sichtbar, wenn die Eigenschaft Rename den Wert True hat.

öffentliche FileEnum FileOptions { abrufen; festlegen; }
[UIHint(Name von (Dateioptionen),"", FileEnum.Umbenennen, FileEnum.Neu erstellen)]
öffentliche Zeichenfolge NeuerDateiname { abrufen; festlegen; }

Das Feld NewFileName ist nur sichtbar, wenn die Auswahl FileOptions entweder Rename oder CreateNew ist.

Standard-Editortyp: DisplayFormatAttribute

[AnzeigeFormat(DataFormatString = "")]

Legt den Standardeingabetyp des Editors fest. Der Parametereingabeeditor versucht, dieses Format zu verwenden, wenn z. B. neue Aufgabenparameter ausgefüllt werden.

Mögliche Werte fürDatenformatzeichenfolgeSind:

• Json

• Text

• Xml

• SQL

• Ausdruck

Beispiel:

[AnzeigeFormat(DataFormatString = "Sql")]
öffentliche Zeichenfolgenabfrage { abrufen; festlegen; }

Parameterfelder mit Registerkarten: PropertyTabAttribute

[Eigenschaftenregisterkarte]

Gruppieren von Parametern als Registerkarten

Beispiel:

öffentliche statische bool Löschen([Eigenschaftsregisterkarte] Zeichenfolge Dateiname, [Eigenschaftsregisterkarte] OptionsClass-Optionen)

Passen Sie die Aufgabenerkennung in FrendsTaskMetadata.json an

Durch Hinzufügen einer FrendsTaskMetadata.json-Datei zum Stamm des NuGet-Pakets können unerwünschte statische Methoden übersprungen werden, indem nur Methoden aufgelistet werden, die als Tasks erwünscht sind. Beispielsweise würde die folgende JSON-Struktur nur dazu führen, dass die DoFileAction als Task betrachtet wird:

{
"Aufgaben": [
        {
"TaskMethod": "Frends.TaskLibrary.FileActions.DoFileAction"
        }
    ]
}

XML-Dokumentation

Benutzerdefinierte Aufgaben können auch im Code kommentiert/dokumentiert werden, indemXML-DokumentationKommentare. Diese Kommentare werden automatisch im Prozessaufgaben-Editor angezeigt, wenn die XML-Dokumentationsdatei im Task-NuGet enthalten ist (wenn die NuGet-ID Frends.TaskLibrary lautet, wird nach einer Datei Frends.TaskLibrary.xml gesucht).

Die Generierung dieser Datei kann automatisch erfolgen, indem beispielsweise die Build/Output/XML-Dokumentation von Visual Studio aktiviert wird. Bei der Abfrage der Kommentare wird zuerst die Task-Parameterdefinition überprüft. Wenn diese nicht gefunden wird, wird die Typdefinition überprüft.

---

Verwandte ArtikelFrends-Aufgaben importieren und aktualisierenBeispiel für AufgabenEinführung in die Json.Handlebars-AufgabeBeispiel zum Importieren benutzerdefinierter AufgabenBeispiel zum Aktualisieren einer Aufgabe