Hinzufügen eines Dashboard-Widgets

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Widgets auf einem Dashboard werden als Beiträge im Erweiterungsframework implementiert. Eine einzelne Erweiterung kann mehrere Beiträge enthalten. Erfahren Sie, wie Sie eine Erweiterung mit mehreren Widgets als Beiträge erstellen.

Dieser Artikel ist in drei Teile unterteilt, die jeweils auf dem vorherigen aufbauen – beginnend mit einem einfachen Widget und endet mit einem umfassenden Widget.

Tipp

Sehen Sie sich unsere neueste Dokumentation zur Erweiterungsentwicklung mithilfe des Azure DevOps-Erweiterungs-SDK an.

Vorbereitung und erforderliche Einrichtung für dieses Tutorial

Zum Erstellen von Erweiterungen für Azure DevOps oder TFS sind einige erforderliche Software und Tools erforderlich:

Wissen: Für die Widgetentwicklung sind Kenntnisse in JavaScript, HTML und CSS erforderlich.

  • Eine Organisation in Azure DevOps zum Installieren und Testen Ihres Widgets. Weitere Informationen finden Sie hier.
  • Ein Text-Editor. Für viele der Tutorials haben wir verwendetVisual Studio Code, die hier heruntergeladen werden können.
  • Die neueste Version des Knotens, die hier heruntergeladen werden kann
  • Plattformübergreifende CLI für Azure DevOps (tfx-cli), um Ihre Erweiterungen zu packen.
    • tfx-cli kann mit npminstalliert werden, einer Komponente von Node.js, indem Sie ausführen. npm i -g tfx-cli
  • Ein Basisverzeichnis für Ihr Projekt. Dieses Verzeichnis wird im gesamten Tutorial als home bezeichnet.

Erweiterungsdateistruktur:

|--- README.md
|--- sdk    
    |--- node_modules           
    |--- scripts
        |--- VSS.SDK.min.js       
|--- img                        
    |--- logo.png                           
|--- scripts                        
|--- hello-world.html               // html page to be used for your widget  
|--- vss-extension.json             // extension's manifest

Was Sie im Tutorial finden

  1. Im ersten Teil dieses Leitfadens erfahren Sie, wie Sie ein neues Widget erstellen, das eine einfache "Hallo Welt"-Nachricht ausgibt.
  2. Der zweite Teil baut auf dem ersten Teil auf, indem ein Aufruf einer Azure DevOps-REST-API hinzugefügt wird.
  3. Im dritten Teil wird erläutert, wie Sie Ihrem Widget Konfiguration hinzufügen.

Hinweis

Wenn Sie es eilig haben und den Code sofort in die Hände bekommen möchten, können Sie die Beispiele hier herunterladen. Wechseln Sie nach dem Herunterladen zum widgets Ordner, und führen Sie dann Schritt 6 und Schritt 7 direkt aus, um die Beispielerweiterung mit den drei Beispielwidgets unterschiedlicher Komplexität zu veröffentlichen.

Erste Schritte mit einigen grundlegenden Stilen für Widgets , die wir Ihnen sofort bereitstellen, und einige Anleitungen zur Widgetstruktur.

Teil 1: Hallo Welt

In diesem Teil wird ein Widget vorgestellt, das "Hallo Welt" mit JavaScript ausgibt.

Übersichtsdashboard mit einem Beispielwidget

Schritt 1: Abrufen des Client-SDK: VSS.SDK.min.js

Das Kern-SDK-Skript ermöglicht VSS.SDK.min.jsWeberweiterungen die Kommunikation mit dem Azure DevOps-Hostframe. Das Skript führt Vorgänge wie initialisieren, die Benachrichtigungserweiterung wird geladen oder der Kontext zur aktuellen Seite abgerufen. Rufen Sie die Client SDK-Datei VSS.SDK.min.js ab, und fügen Sie sie Ihrer Web-App hinzu. Platzieren Sie sie im home/sdk/scripts Ordner.

Verwenden Sie den Befehl "npm install", um das SDK abzurufen:

npm install vss-web-extension-sdk

Weitere Informationen zum SDK finden Sie auf der GitHub-Seite des Client SDK.

Schritt 2: Ihre HTML-Seite : hello-world.html

Ihre HTML-Seite ist der Klebstoff, der Ihr Layout zusammenhält und Verweise auf CSS und JavaScript enthält. Sie können dieser Datei einen beliebigen Namen geben. Stellen Sie sicher, dass Sie alle Verweise auf hello-world den von Ihnen verwendeten Namen aktualisieren.

Ihr Widget basiert auf HTML und wird in einem iframe gehostet. Fügen Sie den folgenden HTML-Code in hinzu hello-world.html. Wir fügen den obligatorischen Verweis auf die Datei hinzu VSS.SDK.min.js und schließen ein h2 -Element in das ein, das mit der Zeichenfolge aktualisiert wird, die im nächsten Schritt Hallo Welt wird.

    <!DOCTYPE html>
    <html>
        <head>          
            <script src="sdk/scripts/VSS.SDK.min.js"></script>              
        </head>
        <body>
            <div class="widget">
                <h2 class="title"></h2>
            </div>
        </body>
    </html>

Obwohl wir eine HTML-Datei verwenden, werden die meisten HTML-Hauptelemente außer Skript und Link vom Framework ignoriert.

Schritt 3: Ihr JavaScript

Wir verwenden JavaScript, um Inhalte im Widget zu rendern. In diesem Artikel umschließen wir den gesamten JavaScript-Code in einem <script> Element in der HTML-Datei. Sie können diesen Code in einer separaten JavaScript-Datei verwenden und in der HTML-Datei darauf verweisen. Der Code rendert den Inhalt. Dieser JavaScript-Code initialisiert auch das VSS SDK, ordnet den Code für Ihr Widget Ihrem Widgetnamen zu und benachrichtigt das Erweiterungsframework über Widgeterfolge oder -fehler. In unserem Fall sehen Sie unten den Code, der "Hallo Welt" im Widget ausgeben würde. Fügen Sie dieses script Element im head HTML-Code hinzu.

    <script type="text/javascript">
        VSS.init({                        
            explicitNotifyLoaded: true,
            usePlatformStyles: true
        });

        VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
            WidgetHelpers.IncludeWidgetStyles();
            VSS.register("HelloWorldWidget", function () {                
                return {
                    load: function (widgetSettings) {
                        var $title = $('h2.title');
                        $title.text('Hello World');

                        return WidgetHelpers.WidgetStatusHelper.Success();
                    }
                }
            });
            VSS.notifyLoadSucceeded();
        });
    </script>

VSS.init Initialisiert den Handshake zwischen dem iframe, der das Widget hostet, und dem Hostframe. Wir übergeben explicitNotifyLoaded: true , damit das Widget den Host explizit benachrichtigen kann, wenn wir mit dem Laden fertig sind. Dieses Steuerelement ermöglicht es uns, den Ladevorgang zu benachrichtigen, nachdem sichergestellt wurde, dass die abhängigen Module geladen werden. Wir übergeben usePlatformStyles: true , damit die Azure DevOps-Kernstile für HTML-Elemente (z. B. body, div usw.) vom Widget verwendet werden können. Wenn das Widget diese Stile lieber nicht verwendet, kann es übergeben usePlatformStyles: false.

VSS.require wird verwendet, um die erforderlichen VSS-Skriptbibliotheken zu laden. Ein Aufruf dieser Methode lädt automatisch allgemeine Bibliotheken wie JQuery und JQueryUI. In unserem Fall sind wir von der WidgetHelpers-Bibliothek abhängig, die verwendet wird, um den Widgetstatus an das Widgetframework zu kommunizieren. Daher übergeben wir den entsprechenden Modulnamen TFS/Dashboards/WidgetHelpers und einen Rückruf an VSS.require. Der Rückruf wird aufgerufen, sobald das Modul geladen wurde. Der Rückruf enthält den Rest des JavaScript-Codes, der für das Widget benötigt wird. Am Ende des Rückrufs rufen wir auf VSS.notifyLoadSucceeded , um den Ladevorgang zu benachrichtigen.

WidgetHelpers.IncludeWidgetStyles enthält ein Stylesheet mit einigen grundlegenden CSS-Dateien , um Ihnen den Einstieg zu erleichtern. Stellen Sie sicher, dass Sie Ihre Inhalte in einem HTML-Element mit -Klasse widget umschließen, um diese Stile zu verwenden.

VSS.register wird verwendet, um eine Funktion in JavaScript zuzuordnen, die das Widget unter den verschiedenen Beiträgen in Ihrer Erweiterung eindeutig identifiziert. Der Name sollte mit dem übereinstimmen, der id Ihren Beitrag identifiziert, wie in Schritt 5 beschrieben. Bei Widgets sollte die Funktion, an die übergeben VSS.register wird, ein Objekt zurückgeben, das den IWidget Vertrag erfüllt. Beispielsweise sollte das zurückgegebene Objekt eine Load-Eigenschaft aufweisen, deren Wert eine andere Funktion ist, die die Kernlogik zum Rendern des Widgets aufweist. In unserem Fall müssen Sie den Text des h2 Elements auf "Hallo Welt" aktualisieren. Es ist diese Funktion, die aufgerufen wird, wenn das Widgetframework Ihr Widget instanziiert. Wir verwenden die WidgetStatusHelper von WidgetHelpers, um den WidgetStatus als erfolgreich zurückzugeben.

Warnung

Wenn der Name, der zum Registrieren des Widgets verwendet wird, nicht mit der ID für den Beitrag im Manifest übereinstimmt, funktioniert das Widget unerwartet.

Der vss-extension.json sollte sich immer im Stammverzeichnis des Ordners befinden (in dieser Anleitung). HelloWorld Für alle anderen Dateien können Sie sie in der gewünschten Struktur im Ordner platzieren. Achten Sie einfach darauf, die Verweise in den HTML-Dateien und im vss-extension.json Manifest entsprechend zu aktualisieren.

Schritt 4: Logo Ihrer Erweiterung: logo.png

Ihr Logo wird im Marketplace und im Widgetkatalog angezeigt, sobald ein Benutzer Ihre Erweiterung installiert hat.

Sie benötigen ein Katalogsymbol mit 98 px x 98 px. Wählen Sie ein Bild aus, nennen Sie es logo.png, und platzieren Sie es im img Ordner.

Um TFS 2015 Update 3 zu unterstützen, benötigen Sie ein zusätzliches Image mit 330 px x 160 px. Dieses Vorschaubild wird in diesem Katalog angezeigt. Wählen Sie ein Bild aus, nennen Sie es preview.png, und platzieren Sie es wie zuvor im img Ordner.

Sie können diese Images beliebig benennen, solange das Erweiterungsmanifest im nächsten Schritt mit den von Ihnen verwendeten Namen aktualisiert wird.

Schritt 5: Manifest Ihrer Erweiterung: vss-extension.json

Erstellen Sie eine JSON-Datei (vss-extension.jsonz. B.) im home Verzeichnis mit dem folgenden Inhalt:

    {
        "manifestVersion": 1,
        "id": "vsts-extensions-myExtensions",
        "version": "1.0.0",
        "name": "My First Set of Widgets",
        "description": "Samples containing different widgets extending dashboards",
        "publisher": "fabrikam",
        "categories": ["Azure Boards"],
        "targets": [
            {
                "id": "Microsoft.VisualStudio.Services"
            }
        ],
        "icons": {
            "default": "img/logo.png"
        },
        "contributions": [
            {
                "id": "HelloWorldWidget",
                "type": "ms.vss-dashboards-web.widget",
                "targets": [
                    "ms.vss-dashboards-web.widget-catalog"
                ],
                "properties": {
                    "name": "Hello World Widget",
                    "description": "My first widget",
                    "catalogIconUrl": "img/CatalogIcon.png",
                    "previewImageUrl": "img/preview.png",                            
                    "uri": "hello-world.html",
                    "supportedSizes": [
                         {
                                "rowSpan": 1,
                                "columnSpan": 2
                            }
                        ],
                    "supportedScopes": ["project_team"]
                }
            }
        ],
        "files": [
            {
                "path": "hello-world.html", "addressable": true
            },
            {
                "path": "sdk/scripts", "addressable": true
            },
            {
                "path": "img", "addressable": true
            }
        ]
    }

Weitere Informationen zu erforderlichen Attributen finden Sie in der Referenz zum Erweiterungsmanifest.

Hinweis

Der Herausgeber muss hier in Ihren Verlegernamen geändert werden. Um jetzt einen Herausgeber zu erstellen, besuchen Sie Paket/Veröffentlichen/Installieren.

Symbole

Die Symbolstrophe gibt den Pfad zum Symbol Ihrer Erweiterung in Ihrem Manifest an.

Beiträge

Jeder Beitragseintrag definiert Eigenschaften.

  • Die ID zum Identifizieren Ihres Beitrags. Diese ID sollte innerhalb einer Erweiterung eindeutig sein. Diese ID sollte mit dem Namen übereinstimmen, den Sie in Schritt 3 zum Registrieren Ihres Widgets verwendet haben.
  • Der Typ des Beitrags. Für alle Widgets sollte der Typ sein ms.vss-dashboards-web.widget.
  • Das Array von Zielen , zu dem der Beitrag beiträgt. Für alle Widgets sollte das Ziel sein [ms.vss-dashboards-web.widget-catalog].
  • Die Eigenschaften sind Objekte, die Eigenschaften für den Beitragstyp enthalten. Für Widgets sind die folgenden Eigenschaften obligatorisch.
Eigenschaft BESCHREIBUNG
name Name des Widgets, das im Widgetkatalog angezeigt werden soll.
Beschreibung Beschreibung des Widgets, das im Widgetkatalog angezeigt werden soll.
catalogIconUrl Relativer Pfad des Katalogsymbols, das Sie in Schritt 4 hinzugefügt haben, um es im Widgetkatalog anzuzeigen. Das Bild sollte 98 px x 98 px sein. Wenn Sie eine andere Ordnerstruktur oder einen anderen Dateinamen verwendet haben, geben Sie hier den entsprechenden relativen Pfad an.
previewImageUrl Relativer Pfad des Vorschaubilds, das Sie in Schritt 4 hinzugefügt haben, um im Widgetkatalog nur für TFS 2015 Update 3 anzuzeigen. Das Bild sollte 330 px x 160 px sein. Wenn Sie eine andere Ordnerstruktur oder einen anderen Dateinamen verwendet haben, geben Sie hier den entsprechenden relativen Pfad an.
uri Relativer Pfad der HTML-Datei, die Sie in Schritt 1 hinzugefügt haben. Wenn Sie eine andere Ordnerstruktur oder einen anderen Dateinamen verwendet haben, geben Sie hier den entsprechenden relativen Pfad an.
supportedSizes Array von Größen, die von Ihrem Widget unterstützt werden. Wenn ein Widget mehrere Größen unterstützt, ist die erste Größe im Array die Standardgröße des Widgets. Wird widget size für die Zeilen und Spalten angegeben, die vom Widget im Dashboardraster belegt werden. Eine Zeile/Spalte entspricht 160 px. Jede Dimension über 1x1 erhält zusätzliche 10 px, die den Rinnser zwischen Widgets darstellen. Beispielsweise ist 160*3+10*2 ein 3x2-Widget breit und 160*2+10*1 hoch. Die maximal unterstützte Größe ist 4x4.
supportedScopes Derzeit unterstützen wir nur Teamdashboards. Der Wert muss sein project_team. Wenn wir in Zukunft andere Dashboardbereiche unterstützen, stehen hier weitere Optionen zur Auswahl.

Dateien

In der Dateistundanz werden die Dateien angegeben, die Sie in Ihr Paket einschließen möchten: Ihre HTML-Seite, Ihre Skripts, das SDK-Skript und Ihr Logo. Legen Sie auf fest addressabletrue , es sei denn, Sie schließen andere Dateien ein, die nicht URL-adressierbar sein müssen.

Hinweis

Weitere Informationen zur Erweiterungsmanifestdatei, z. B. zu ihren Eigenschaften und deren Funktionsweise, finden Sie in der Erweiterungsmanifestreferenz.

Schritt 6: Packen, Veröffentlichen und Freigeben

Nachdem Sie Ihre Erweiterung geschrieben haben, besteht der nächste Schritt, um sie in den Marketplace zu bringen, darin, alle Ihre Dateien zusammenzupacken. Alle Erweiterungen werden als VSIX 2.0-kompatible VSIX-Dateien gepackt. Microsoft stellt eine plattformübergreifende Befehlszeilenschnittstelle (CLI) zum Verpacken Ihrer Erweiterung bereit.

Abrufen des Paketerstellungstools

Sie können die plattformübergreifende CLI für Azure DevOps (tfx-cli) mithilfe npmvon , einer Komponente von Node.js, über die Befehlszeile installieren oder aktualisieren.

npm i -g tfx-cli

Packen der Erweiterung

Das Packen der Erweiterung in eine VSIX-Datei ist mühelos, sobald Sie über die tfx-cli verfügen. Wechseln Sie zum Basisverzeichnis Ihrer Erweiterung, und führen Sie den folgenden Befehl aus.

tfx extension create --manifest-globs vss-extension.json

Hinweis

Die Version einer Erweiterung/Integration muss bei jedem Update erhöht werden.
Wenn Sie eine vorhandene Erweiterung aktualisieren, aktualisieren Sie entweder die Version im Manifest, oder übergeben Sie den Befehlszeilenschalter --rev-version . Dadurch wird die Patchversionsnummer Ihrer Erweiterung erhöht, und die neue Version wird in Ihrem Manifest gespeichert.

Nachdem Sie ihre gepackte Erweiterung in einer VSIX-Datei enthalten haben, können Sie Ihre Erweiterung im Marketplace veröffentlichen.

Erstellen eines Herausgebers für die Erweiterung

Alle Erweiterungen, einschließlich Erweiterungen von Microsoft, werden als von einem Herausgeber bereitgestellt identifiziert. Wenn Sie noch kein Mitglied eines vorhandenen Herausgebers sind, erstellen Sie einen.

  1. Anmelden beim Visual Studio Marketplace-Veröffentlichungsportal
  2. Wenn Sie noch kein Mitglied eines vorhandenen Herausgebers sind, werden Sie aufgefordert, einen Herausgeber zu erstellen. Wenn Sie nicht aufgefordert werden, einen Herausgeber zu erstellen, scrollen Sie nach unten bis zum Ende der Seite, und wählen Sie Erweiterungen veröffentlichen unter Verwandte Websites aus.
    • Geben Sie einen Bezeichner für Ihren Herausgeber an, z. B.: mycompany-myteam
      • Der Bezeichner wird als Wert für das Attribut in der publisher Manifestdatei Ihrer Erweiterungen verwendet.
    • Geben Sie einen Anzeigenamen für Ihren Herausgeber an, z. B.: My Team
  3. Überprüfen Sie die Marketplace-Herausgebervereinbarung, und wählen Sie Erstellen aus.

Jetzt ist Ihr Herausgeber definiert. In einer zukünftigen Version können Sie Berechtigungen zum Anzeigen und Verwalten der Erweiterungen Ihres Herausgebers erteilen. Es ist für Teams und Organisationen einfach und sicherer, Erweiterungen unter einem gemeinsamen Herausgeber zu veröffentlichen, ohne jedoch eine Reihe von Anmeldeinformationen für eine Gruppe von Benutzern freigeben zu müssen.

Aktualisieren Sie die vss-extension.json Manifestdatei in den Beispielen, um die Dummy-Herausgeber-ID fabrikam durch Ihre Herausgeber-ID zu ersetzen.

Veröffentlichen und Freigeben der Erweiterung

Nachdem Sie einen Herausgeber erstellt haben, können Sie Ihre Erweiterung jetzt in den Marketplace hochladen.

  1. Suchen Sie die Schaltfläche Neue Erweiterung hochladen , navigieren Sie zu Ihrer gepackten VSIX-Datei, und wählen Sie Hochladen aus.

Sie können Ihre Erweiterung auch über die Befehlszeile hochladen, indem Sie den tfx extension publish Befehl verwenden, anstatt tfx extension create Ihre Erweiterung in einem Schritt zu packen und zu veröffentlichen. Sie können optional verwenden --share-with , um Ihre Erweiterung nach der Veröffentlichung mit einem oder mehreren Konten zu teilen. Sie benötigen auch ein persönliches Zugriffstoken.

tfx extension publish --manifest-globs your-manifest.json --share-with yourOrganization

Schritt 7: Hinzufügen eines Widgets aus dem Katalog

  1. Navigieren Sie zu Ihrem Projekt in Azure DevOps. http://dev.azure.com/{yourOrganization}/{yourProject}

  2. Wählen Sie Übersicht und dann Dashboards aus.

  3. Wählen Sie Widget hinzufügen aus.

  4. Markieren Sie Ihr Widget, und wählen Sie dann Hinzufügen aus.

    Das Widget wird auf Ihrem Dashboard angezeigt.

Teil 2: Hallo Welt mit der Azure DevOps-REST-API

Widgets können jede der REST-APIs in Azure DevOps aufrufen, um mit Azure DevOps-Ressourcen zu interagieren. In diesem Beispiel verwenden wir die REST-API für WorkItemTracking, um Informationen zu einer vorhandenen Abfrage abzurufen und einige Abfrageinformationen im Widget direkt unter dem Text "Hallo Welt" anzuzeigen.

Übersichtsdashboard mit einem Beispielwidget, das die REST-API für WorkItemTracking verwendet.

Schritt 1: HTML

Kopieren Sie die Datei hello-world.html aus dem vorherigen Beispiel, und benennen Sie die Kopie in um hello-world2.html. Ihr Ordner sieht nun wie folgt aus:

|--- README.md
|--- sdk    
    |--- node_modules           
    |--- scripts
        |--- VSS.SDK.min.js       
|--- img                        
    |--- logo.png                           
|--- scripts                        
|--- hello-world.html               // html page to be used for your widget  
|--- hello-world2.html              // renamed copy of hello-world.html
|--- vss-extension.json             // extension's manifest

Fügen Sie direkt unterhalb von h2 ein neues div Element hinzu, um die Abfrageinformationen zu enthalten. Aktualisieren Sie den Namen des Widgets von HelloWorldWidget in HelloWorldWidget2 der Zeile, in der Sie aufrufen VSS.register. Dadurch kann das Framework das Widget innerhalb der Erweiterung eindeutig identifizieren.
<!DOCTYPE html>
<html>
    <head>                          
        <script src="sdk/scripts/VSS.SDK.min.js"></script>              
        <script type="text/javascript">
            VSS.init({
                explicitNotifyLoaded: true,
                usePlatformStyles: true
            });

            VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
                WidgetHelpers.IncludeWidgetStyles();
                VSS.register("HelloWorldWidget2", function () {                
                    return {
                        load: function (widgetSettings) {
                            var $title = $('h2.title');
                            $title.text('Hello World');

                            return WidgetHelpers.WidgetStatusHelper.Success();
                        }
                    }
                });
                VSS.notifyLoadSucceeded();
            });       
        </script>
    </head>
    <body>
        <div class="widget">
            <h2 class="title"></h2>
            <div id="query-info-container"></div>
        </div>
    </body>
</html>

Schritt 2: Zugreifen auf Azure DevOps-Ressourcen

Um den Zugriff auf Azure DevOps-Ressourcen zu ermöglichen, müssen Bereiche im Erweiterungsmanifest angegeben werden. Wir fügen den vso.work Bereich zu unserem Manifest hinzu.
Dieser Bereich gibt an, dass das Widget schreibgeschützten Zugriff auf Abfragen und Arbeitselemente benötigt. Alle verfügbaren Bereiche finden Sie hier. Fügen Sie unten am Ende Ihres Erweiterungsmanifests hinzu.

{
    ...,
    "scopes":[
        "vso.work"
    ]
}

Warnung

Das Hinzufügen oder Ändern von Bereichen nach dem Veröffentlichen einer Erweiterung wird derzeit nicht unterstützt. Wenn Sie Ihre Erweiterung bereits hochgeladen haben, entfernen Sie sie aus dem Marketplace. Navigieren Sie zum Visual Studio Marketplace-Veröffentlichungsportal, klicken Sie mit der rechten Maustaste auf Ihre Erweiterung, und wählen Sie "Entfernen" aus.

Schritt 3: Ausführen des REST-API-Aufrufs

Es gibt viele clientseitige Bibliotheken, auf die über das SDK zugegriffen werden kann, um REST-API-Aufrufe in Azure DevOps zu tätigen. Diese Bibliotheken werden REST-Clients genannt und sind JavaScript-Wrapper um Ajax-Aufrufe für alle verfügbaren serverseitigen Endpunkte. Sie können von diesen Clients bereitgestellte Methoden verwenden, anstatt Ajax-Aufrufe selbst zu schreiben. Diese Methoden ordnen die API-Antworten Objekten zu, die von Ihrem Code genutzt werden können.

In diesem Schritt aktualisieren wir den VSS.require Aufruf zum Laden TFS/WorkItemTracking/RestClient, der den WorkItemTracking-REST-Client bereitstellt. Wir können diesen REST-Client verwenden, um Informationen zu einer Abfrage abzurufen, die unter dem Ordner Shared Queriesaufgerufen wirdFeedback.

In der Funktion, die an übergeben wird VSS.register, erstellen wir eine Variable, die die aktuelle Projekt-ID enthält. Wir benötigen diese Variable, um die Abfrage abzurufen. Außerdem erstellen wir eine neue Methode getQueryInfo , um den REST-Client zu verwenden. Diese Methode, die dann von der Load-Methode aufgerufen wird.

Die -Methode getClient gibt eine Instanz des benötigten REST-Clients an. Die -Methode getQuery gibt die Abfrage zurück, die mit einer Zusage umschlossen ist. Das aktualisierte VSS.require Sieht wie folgt aus:

VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], 
    function (WidgetHelpers, TFS_Wit_WebApi) {
        WidgetHelpers.IncludeWidgetStyles();
        VSS.register("HelloWorldWidget2", function () { 
            var projectId = VSS.getWebContext().project.id;

            var getQueryInfo = function (widgetSettings) {
                // Get a WIT client to make REST calls to Azure DevOps Services
                return TFS_Wit_WebApi.getClient().getQuery(projectId, "Shared Queries/Feedback")
                    .then(function (query) {
                        // Do something with the query

                        return WidgetHelpers.WidgetStatusHelper.Success();
                    }, function (error) {                            
                        return WidgetHelpers.WidgetStatusHelper.Failure(error.message);
                    });
            }

            return {
                load: function (widgetSettings) {
                    // Set your title
                    var $title = $('h2.title');
                    $title.text('Hello World');

                    return getQueryInfo(widgetSettings);
                }
            }
        });
        VSS.notifyLoadSucceeded();
    });

Beachten Sie die Verwendung der Failure-Methode von WidgetStatusHelper. Damit können Sie dem Widgetframework angeben, dass ein Fehler aufgetreten ist, und die Standardfehlererfahrung nutzen, die allen Widgets zur Verfügung gestellt wird.

Wenn Sie die Feedback Abfrage nicht unter dem Shared Queries Ordner haben, ersetzen Sie Shared Queries\Feedback im Code durch den Pfad einer Abfrage, die in Ihrem Projekt vorhanden ist.

Schritt 4: Anzeigen der Antwort

Der letzte Schritt besteht darin, die Abfrageinformationen innerhalb des Widgets zu rendern. Die getQuery Funktion gibt ein Objekt vom Typ Contracts.QueryHierarchyItem innerhalb einer Zusage zurück. In diesem Beispiel werden die Abfrage-ID, der Abfragename und der Name des Abfrageerstellers unter dem Text "Hallo Welt" angezeigt. Ersetzen Sie den // Do something with the query Kommentar durch den folgenden:

    // Create a list with query details                                
    var $list = $('<ul>');                                
    $list.append($('<li>').text("Query Id: " + query.id));
    $list.append($('<li>').text("Query Name: " + query.name));
    $list.append($('<li>').text("Created By: " + ( query.createdBy? query.createdBy.displayName: "<unknown>" ) ) );                                                            

    // Append the list to the query-info-container
    var $container = $('#query-info-container');
    $container.empty();
    $container.append($list);

Ihr Finale hello-world2.html lautet wie folgt:

<!DOCTYPE html>
<html>
<head>    
    <script src="sdk/scripts/VSS.SDK.min.js"></script>
    <script type="text/javascript">
        VSS.init({
            explicitNotifyLoaded: true,
            usePlatformStyles: true
        });

        VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"], 
            function (WidgetHelpers, TFS_Wit_WebApi) {
                WidgetHelpers.IncludeWidgetStyles();
                VSS.register("HelloWorldWidget2", function () {                
                    var projectId = VSS.getWebContext().project.id;

                    var getQueryInfo = function (widgetSettings) {
                        // Get a WIT client to make REST calls to Azure DevOps Services
                        return TFS_Wit_WebApi.getClient().getQuery(projectId, "Shared Queries/Feedback")
                            .then(function (query) {
                                // Create a list with query details                                
                                var $list = $('<ul>');
                                $list.append($('<li>').text("Query ID: " + query.id));
                                $list.append($('<li>').text("Query Name: " + query.name));
                                $list.append($('<li>').text("Created By: " + (query.createdBy ? query.createdBy.displayName: "<unknown>") ));

                                // Append the list to the query-info-container
                                var $container = $('#query-info-container');
                                $container.empty();
                                $container.append($list);

                                // Use the widget helper and return success as Widget Status
                                return WidgetHelpers.WidgetStatusHelper.Success();
                            }, function (error) {
                                // Use the widget helper and return failure as Widget Status
                                return WidgetHelpers.WidgetStatusHelper.Failure(error.message);
                            });
                    }

                    return {
                        load: function (widgetSettings) {
                            // Set your title
                            var $title = $('h2.title');
                            $title.text('Hello World');

                            return getQueryInfo(widgetSettings);
                        }
                    }
                });
            VSS.notifyLoadSucceeded();
        });       
    </script>

</head>
<body>
    <div class="widget">
        <h2 class="title"></h2>
        <div id="query-info-container"></div>
    </div>
</body>
</html>

Schritt 5: Erweiterungsmanifest Aktualisierungen

In diesem Schritt aktualisieren wir das Erweiterungsmanifest so, dass es einen Eintrag für unser zweites Widget enthält. Fügen Sie einen neuen Beitrag zum Array in der contributions -Eigenschaft hinzu, und fügen Sie die neue Datei hello-world2.html dem Array in der files-Eigenschaft hinzu. Sie benötigen ein weiteres Vorschaubild für das zweite Widget. Nennen Sie diesen preview2.png Namen, und platzieren Sie sie im img Ordner.

 {
     ...,
     "contributions":[
         ...,
        {
             "id": "HelloWorldWidget2",
             "type": "ms.vss-dashboards-web.widget",
             "targets": [
                 "ms.vss-dashboards-web.widget-catalog"
             ],
             "properties": {
                 "name": "Hello World Widget 2 (with API)",
                 "description": "My second widget",
                 "previewImageUrl": "img/preview2.png",                            
                 "uri": "hello-world2.html",
                 "supportedSizes": [
                      {
                             "rowSpan": 1,
                             "columnSpan": 2
                         }
                     ],
                 "supportedScopes": ["project_team"]
             }
         }

     ],
     "files": [
         {
             "path": "hello-world.html", "addressable": true
         },
         {
             "path": "hello-world2.html", "addressable": true
         },      
         {
             "path": "sdk/scripts", "addressable": true
         },
         {
             "path": "img", "addressable": true
         }
     ],
     "scopes":[
         "vso.work"
     ]
 }

Schritt 6: Paket, Veröffentlichen und Freigeben

Packen, veröffentlichen und freigeben Sie Ihre Erweiterung. Wenn Sie die Erweiterung bereits veröffentlicht haben, können Sie die Erweiterung wie hier beschrieben neu packen und direkt auf den Marketplace aktualisieren .

Schritt 7: Hinzufügen eines Widgets aus dem Katalog

Wechseln Sie nun zu Ihrem Teamdashboard unter https:\//dev.azure.com/{yourOrganization}/{yourProject}. Wenn diese Seite bereits geöffnet ist, aktualisieren Sie sie. Zeigen Sie unten rechts auf die Schaltfläche Bearbeiten, und wählen Sie die Schaltfläche Hinzufügen aus. Der Widgetkatalog wird geöffnet, wo Sie das widget finden, das Sie installiert haben. Wählen Sie Ihr Widget aus, und wählen Sie die Schaltfläche "Hinzufügen", um es Ihrem Dashboard hinzuzufügen.

Teil 3: Hallo Welt mit Konfiguration

In Teil 2 dieses Leitfadens haben Sie erfahren, wie Sie ein Widget erstellen, das Abfrageinformationen für eine hartcodierte Abfrage anzeigt. In diesem Teil fügen wir die Möglichkeit hinzu, die zu verwendende Abfrage anstelle der hartcodierten zu konfigurieren. Im Konfigurationsmodus wird dem Benutzer basierend auf seinen Änderungen eine Livevorschau des Widgets angezeigt. Diese Änderungen werden im Widget auf dem Dashboard gespeichert, wenn der Benutzer Speichern auswählt.

Übersichtsdashboard: Livevorschau des Widgets basierend auf Änderungen.

Schritt 1: HTML

Implementierungen von Widgets und Widgetkonfigurationen sind sehr ähnlich. Beide werden im Erweiterungsframework als Beiträge implementiert. Beide verwenden dieselbe SDK-Datei, VSS.SDK.min.js. Beide basieren auf HTML, JavaScript und CSS.

Kopieren Sie die Datei html-world2.html aus dem vorherigen Beispiel, und benennen Sie die Kopie in um hello-world3.html. Fügen Sie eine weitere HTML-Datei mit dem Namen hinzu configuration.html. Ihr Ordner sieht nun wie im folgenden Beispiel aus:

|--- README.md
|--- sdk    
    |--- node_modules           
    |--- scripts
        |--- VSS.SDK.min.js       
|--- img                        
    |--- logo.png                           
|--- scripts          
|--- configuration.html                          
|--- hello-world.html               // html page to be used for your widget  
|--- hello-world2.html              // renamed copy of hello-world.html
|--- hello-world3.html              // renamed copy of hello-world2.html
|--- vss-extension.json             // extension's manifest

Fügen Sie den folgenden HTML-Code in hinzu configuration.html. Wir fügen grundsätzlich den obligatorischen Verweis auf die VSS.SDK.min.js Datei und ein select Element für die Dropdownliste hinzu, um eine Abfrage aus einer voreingestellten Liste auszuwählen.
    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml">
        <head>                          
            <script src="sdk/scripts/VSS.SDK.min.js"></script>              
        </head>
        <body>
            <div class="container">
                <fieldset>
                    <label class="label">Query: </label>
                    <select id="query-path-dropdown" style="margin-top:10px">
                        <option value="" selected disabled hidden>Please select a query</option>
                        <option value="Shared Queries/Feedback">Shared Queries/Feedback</option>
                        <option value="Shared Queries/My Bugs">Shared Queries/My Bugs</option>
                        <option value="Shared Queries/My Tasks">Shared Queries/My Tasks</option>                        
                    </select>
                </fieldset>             
            </div>
        </body>
    </html>

Schritt 2: JavaScript – Konfiguration

Verwenden Sie JavaScript, um Inhalte in der Widgetkonfiguration wie für das Widget in Schritt 3 von Teil 1 in diesem Leitfaden zu rendern. Dieser JavaScript-Code rendert Inhalte, initialisiert das VSS SDK, ordnet den Code für Ihre Widgetkonfiguration dem Konfigurationsnamen zu und übergibt die Konfigurationseinstellungen an das Framework. In unserem Fall sehen Sie unten den Code, der die Widgetkonfiguration lädt. Öffnen Sie die Datei configuration.html und das folgende <script> Element für .<head>

    <script type="text/javascript">
        VSS.init({                        
            explicitNotifyLoaded: true,
            usePlatformStyles: true
        });

        VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
            VSS.register("HelloWorldWidget.Configuration", function () {   
                var $queryDropdown = $("#query-path-dropdown"); 

                return {
                    load: function (widgetSettings, widgetConfigurationContext) {
                        var settings = JSON.parse(widgetSettings.customSettings.data);
                        if (settings && settings.queryPath) {
                             $queryDropdown.val(settings.queryPath);
                         }

                        return WidgetHelpers.WidgetStatusHelper.Success();
                    },
                    onSave: function() {
                        var customSettings = {
                            data: JSON.stringify({
                                    queryPath: $queryDropdown.val()
                                })
                        };
                        return WidgetHelpers.WidgetConfigurationSave.Valid(customSettings); 
                    }
                }
            });
            VSS.notifyLoadSucceeded();
        });
    </script>

VSS.init, VSS.requireund VSS.register spielen die gleiche Rolle wie für das Widget, wie in Teil 1 beschrieben. Der einzige Unterschied besteht darin, dass bei Widgetkonfigurationen die Funktion, an VSS.register die übergeben wird, ein Objekt zurückgeben soll, das den IWidgetConfiguration Vertrag erfüllt.

Die load Eigenschaft des IWidgetConfiguration Vertrags sollte eine Funktion als Wert aufweisen. Diese Funktion verfügt über die Schritte zum Rendern der Widgetkonfiguration. In unserem Fall müssen Sie den ausgewählten Wert des Dropdownelements mit vorhandenen Einstellungen aktualisieren, falls vorhanden. Diese Funktion wird aufgerufen, wenn das Framework Ihre Instanziierung widget configuration

Die onSave Eigenschaft des IWidgetConfiguration Vertrags sollte eine Funktion als Wert aufweisen. Diese Funktion wird vom Framework aufgerufen, wenn der Benutzer im Konfigurationsbereich Speichern auswählt. Wenn die Benutzereingabe zum Speichern bereit ist, serialisieren Sie sie in eine Zeichenfolge, bilden das custom settings Objekt aus, und speichern WidgetConfigurationSave.Valid() Sie die Benutzereingabe.

In dieser Anleitung verwenden wir JSON, um die Benutzereingabe in eine Zeichenfolge zu serialisieren. Sie können eine beliebige andere Möglichkeit auswählen, um die Benutzereingabe in Zeichenfolge zu serialisieren. Auf das Widget kann über die customSettings-Eigenschaft des WidgetSettings Objekts zugegriffen werden. Das Widget muss dies deserialisieren, was in Schritt 4 behandelt wird.

Schritt 3: JavaScript – Aktivieren der Livevorschau

Um die Livevorschauaktualisierung zu aktivieren, wenn der Benutzer eine Abfrage aus der Dropdownliste auswählt, fügen wir der Schaltfläche einen Änderungsereignishandler an. Dieser Handler benachrichtigt das Framework, dass die Konfiguration geändert wurde. Es übergibt auch den, der customSettings zum Aktualisieren der Vorschau verwendet werden soll. Um das Framework zu benachrichtigen, muss die notify -Methode für aufgerufen widgetConfigurationContext werden. Es benötigt zwei Parameter, den Namen des Ereignisses, der in diesem Fall ist WidgetHelpers.WidgetEvent.ConfigurationChange, und ein EventArgs Objekt für das Ereignis, das customSettings mit Hilfe der WidgetEvent.Args Hilfsmethode erstellt wurde.

Fügen Sie den folgenden in der Funktion hinzu, die der load -Eigenschaft zugewiesen ist.

 $queryDropdown.on("change", function () {
     var customSettings = {
        data: JSON.stringify({
                queryPath: $queryDropdown.val()
            })
     };
     var eventName = WidgetHelpers.WidgetEvent.ConfigurationChange;
     var eventArgs = WidgetHelpers.WidgetEvent.Args(customSettings);
     widgetConfigurationContext.notify(eventName, eventArgs);
 });

Sie müssen das Framework mindestens einmal über Konfigurationsänderungen benachrichtigen, damit die Schaltfläche "Speichern" aktiviert werden kann.

Am Ende sieht Ihr configuration.html wie folgt aus:

    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml">
        <head>                          
            <script src="sdk/scripts/VSS.SDK.min.js"></script>      
            <script type="text/javascript">
                VSS.init({                        
                    explicitNotifyLoaded: true,
                    usePlatformStyles: true
                });

                VSS.require("TFS/Dashboards/WidgetHelpers", function (WidgetHelpers) {
                    VSS.register("HelloWorldWidget.Configuration", function () {   
                        var $queryDropdown = $("#query-path-dropdown");

                        return {
                            load: function (widgetSettings, widgetConfigurationContext) {
                                var settings = JSON.parse(widgetSettings.customSettings.data);
                                if (settings && settings.queryPath) {
                                     $queryDropdown.val(settings.queryPath);
                                 }

                                 $queryDropdown.on("change", function () {
                                     var customSettings = {data: JSON.stringify({queryPath: $queryDropdown.val()})};
                                     var eventName = WidgetHelpers.WidgetEvent.ConfigurationChange;
                                     var eventArgs = WidgetHelpers.WidgetEvent.Args(customSettings);
                                     widgetConfigurationContext.notify(eventName, eventArgs);
                                 });

                                return WidgetHelpers.WidgetStatusHelper.Success();
                            },
                            onSave: function() {
                                var customSettings = {data: JSON.stringify({queryPath: $queryDropdown.val()})};
                                return WidgetHelpers.WidgetConfigurationSave.Valid(customSettings); 
                            }
                        }
                    });
                    VSS.notifyLoadSucceeded();
                });
            </script>       
        </head>
        <body>
            <div class="container">
                <fieldset>
                    <label class="label">Query: </label>
                    <select id="query-path-dropdown" style="margin-top:10px">
                        <option value="" selected disabled hidden>Please select a query</option>
                        <option value="Shared Queries/Feedback">Shared Queries/Feedback</option>
                        <option value="Shared Queries/My Bugs">Shared Queries/My Bugs</option>
                        <option value="Shared Queries/My Tasks">Shared Queries/My Tasks</option>                        
                    </select>
                </fieldset>     
            </div>
        </body>
    </html>

Schritt 4: JavaScript: Implementieren des Neuladens im Widget

Wir haben die Widgetkonfiguration eingerichtet, um den vom Benutzer ausgewählten Abfragepfad zu speichern. Wir müssen jetzt den Code im Widget aktualisieren, um diese gespeicherte Konfiguration anstelle der hartcodierten Shared Queries/Feedback aus dem vorherigen Beispiel zu verwenden.

Öffnen Sie die Datei hello-world3.html , und aktualisieren Sie den Namen des Widgets von HelloWorldWidget2 in HelloWorldWidget3 der Zeile, in der Sie aufrufen VSS.register. Dadurch kann das Framework das Widget innerhalb der Erweiterung eindeutig identifizieren.

Die über zugeordnete HelloWorldWidget3VSS.register Funktion gibt derzeit ein Objekt zurück, das den IWidget Vertrag erfüllt. Da unser Widget jetzt konfiguriert werden muss, muss diese Funktion aktualisiert werden, um ein Objekt zurückzugeben, das den IConfigurableWidget Vertrag erfüllt. Aktualisieren Sie hierzu die return-Anweisung so, dass sie eine Eigenschaft mit dem Namen reload enthält. Der Wert für diese Eigenschaft ist eine Funktion, die die getQueryInfo Methode einmal mehr aufruft. Diese Neulademethode wird vom Framework jedes Mal aufgerufen, wenn sich die Benutzereingabe ändert, um die Livevorschau anzuzeigen. Dies wird auch aufgerufen, wenn die Konfiguration gespeichert wird.

return {
    load: function (widgetSettings) {
        // Set your title
        var $title = $('h2.title');
        $title.text('Hello World');

        return getQueryInfo(widgetSettings);
    },
    reload: function (widgetSettings) {
        return getQueryInfo(widgetSettings);
    }
}

Der hartcodierte Abfragepfad in getQueryInfo sollte durch den konfigurierten Abfragepfad ersetzt werden, der aus dem Parameter widgetSettings extrahiert werden kann, der an die -Methode übergeben wird. Fügen Sie ganz am Anfang der -Methode folgendes getQueryInfo hinzu, und ersetzen Sie den hartcodierten Abfragepfad durch settings.queryPath.
var settings = JSON.parse(widgetSettings.customSettings.data);
if (!settings || !settings.queryPath) {
    var $container = $('#query-info-container');
    $container.empty();
    $container.text("Sorry nothing to show, please configure a query path.");

    return WidgetHelpers.WidgetStatusHelper.Success();
}

An diesem Punkt kann Ihr Widget mit den konfigurierten Einstellungen gerendert werden.

Sowohl die load -Eigenschaft als auch die reload -Eigenschaft haben eine ähnliche Funktion. Dies ist für die meisten einfachen Widgets der Fall. Bei komplexen Widgets gibt es bestimmte Vorgänge, die Sie nur einmal ausführen möchten, unabhängig davon, wie oft sich die Konfiguration ändert. Oder es gibt einige schwergewichtige Vorgänge, die nicht mehr als einmal ausgeführt werden müssen. Solche Vorgänge wären Teil der Funktion, die der load -Eigenschaft und nicht der reload -Eigenschaft entspricht.

Schritt 5: Erweiterungsmanifest Aktualisierungen

Öffnen Sie die vss-extension.json Datei, um zwei neue Einträge in das Array in die contributions -Eigenschaft aufzunehmen. Eine für das HelloWorldWidget3 Widget und die andere für dessen Konfiguration. Sie benötigen ein weiteres Vorschaubild für das dritte Widget. Nennen Sie diesen preview3.png Namen, und platzieren Sie sie im img Ordner. Aktualisieren Sie das Array in der files -Eigenschaft, um die beiden neuen HTML-Dateien einzuschließen, die wir in diesem Beispiel hinzugefügt haben.

{
    ...
    "contributions": [
        ... , 
        {
             "id": "HelloWorldWidget3",
             "type": "ms.vss-dashboards-web.widget",
             "targets": [
                 "ms.vss-dashboards-web.widget-catalog",
                 "fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration"
             ],
             "properties": {
                 "name": "Hello World Widget 3 (with config)",
                 "description": "My third widget",
                 "previewImageUrl": "img/preview3.png",                       
                 "uri": "hello-world3.html",
                 "supportedSizes": [
                      {
                             "rowSpan": 1,
                             "columnSpan": 2
                         }
                     ],
                 "supportedScopes": ["project_team"]
             }
         },
         {
             "id": "HelloWorldWidget.Configuration",
             "type": "ms.vss-dashboards-web.widget-configuration",
             "targets": [ "ms.vss-dashboards-web.widget-configuration" ],
             "properties": {
                 "name": "HelloWorldWidget Configuration",
                 "description": "Configures HelloWorldWidget",
                 "uri": "configuration.html"
             }
         }
    ],
    "files": [
            {
                "path": "hello-world.html", "addressable": true
            },
             {
                "path": "hello-world2.html", "addressable": true
            },
            {
                "path": "hello-world3.html", "addressable": true
            },
            {
                "path": "configuration.html", "addressable": true
            },
            {
                "path": "sdk/scripts", "addressable": true
            },
            {
                "path": "img", "addressable": true
            }
        ],
        ...     
}

Beachten Sie, dass der Beitrag für die Widgetkonfiguration einem etwas anderen Modell als dem Widget selbst folgt. Ein Beitragseintrag für die Widgetkonfiguration hat Folgendes:
  • Die ID , um Ihren Beitrag zu identifizieren. Dies sollte innerhalb einer Erweiterung eindeutig sein.
  • Die Art des Beitrags. Für alle Widgetkonfigurationen sollte dies sein. ms.vss-dashboards-web.widget-configuration
  • Das Array von Zielen , zu denen der Beitrag beiträgt. Für alle Widgetkonfigurationen hat dies einen einzigen Eintrag: ms.vss-dashboards-web.widget-configuration.
  • Die Eigenschaften , die einen Satz von Eigenschaften enthalten, die den Namen, die Beschreibung und den URI der für die Konfiguration verwendeten HTML-Datei enthalten.

Um die Konfiguration zu unterstützen, muss auch der Widgetbeitrag geändert werden. Das Array von Zielen für das Widget muss aktualisiert werden, um die ID für die Konfiguration in der Form <>publisher.<id for the extension>.id for the configuration contribution<> einzuschließen, die in diesem Fall ist.fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration

Warnung

Wenn der Beitragseintrag für Ihr konfigurierbares Widget nicht auf die Konfiguration mit dem richtigen Herausgeber- und Erweiterungsnamen ausgerichtet ist, wie zuvor beschrieben, wird die Schaltfläche Konfigurieren für das Widget nicht angezeigt.

Am Ende dieses Teils sollte die Manifestdatei drei Widgets und eine Konfiguration enthalten. Hier können Sie das vollständige Manifest aus dem Beispiel abrufen.

Schritt 6: Paket, Veröffentlichen und Freigeben

Wenn Sie Ihre Erweiterung noch nicht veröffentlicht haben, lesen Sie diesen Abschnitt , um Ihre Erweiterung zu packen, zu veröffentlichen und zu teilen. Wenn Sie die Erweiterung bereits vor diesem Punkt veröffentlicht haben, können Sie die Erweiterung wie hier beschrieben neu packen und direkt auf den Marketplace aktualisieren .

Schritt 7: Hinzufügen eines Widgets aus dem Katalog

Wechseln Sie nun zu Ihrem Teamdashboard unter https://dev.azure.com/{yourOrganization}/{yourProject}. Wenn diese Seite bereits geöffnet ist, aktualisieren Sie sie. Zeigen Sie unten rechts auf die Schaltfläche Bearbeiten, und wählen Sie die Schaltfläche Hinzufügen aus. Dadurch sollte der Widgetkatalog geöffnet werden, in dem Sie das widget finden, das Sie installiert haben. Wählen Sie Ihr Widget aus, und wählen Sie die Schaltfläche "Hinzufügen", um es Ihrem Dashboard hinzuzufügen.

Es wird eine Meldung angezeigt, in der Sie aufgefordert werden, das Widget zu konfigurieren.

Übersichtsdashboard mit einem Beispielwidget aus dem Katalog.

Es gibt zwei Möglichkeiten, Widgets zu konfigurieren. Eine besteht darin, auf das Widget zu zeigen, die Auslassungspunkte auszuwählen, die in der oberen rechten Ecke angezeigt werden, und wählen Sie dann Konfigurieren aus. Zum anderen wählen Sie unten rechts im Dashboard die Schaltfläche Bearbeiten und dann die Schaltfläche Konfigurieren aus, die in der oberen rechten Ecke des Widgets angezeigt wird. Entweder öffnet die Konfigurationsoberfläche auf der rechten Seite und eine Vorschau Ihres Widgets in der Mitte. Wählen Sie eine Abfrage aus der Dropdownliste aus. Die Livevorschau zeigt die aktualisierten Ergebnisse an. Wählen Sie "Speichern" aus, und Ihr Widget zeigt die aktualisierten Ergebnisse an.

Schritt 8: Konfigurieren von Mehr (optional)

Sie können so viele HTML-Formularelemente hinzufügen, wie Sie für zusätzliche configuration.html Konfiguration benötigen. Es gibt zwei konfigurierbare Features, die sofort verfügbar sind: Widgetname und Widgetgröße.

Standardmäßig wird der Name, den Sie für Ihr Widget im Erweiterungsmanifest angeben, als Widgetname für jede Instanz Ihres Widgets gespeichert, die jemals einem Dashboard hinzugefügt wird. Sie können Benutzern erlauben, dies zu konfigurieren, sodass sie ihrer Instanz Ihres Widgets einen beliebigen Namen hinzufügen können. Um eine solche Konfiguration zuzulassen, fügen Sie isNameConfigurable:true im Abschnitt Eigenschaften für Ihr Widget im Erweiterungsmanifest hinzu.

Wenn Sie im Erweiterungsmanifest mehrere Einträge für Ihr Widget im supportedSizes Array angeben, können Benutzer auch die Größe des Widgets konfigurieren.

Das Erweiterungsmanifest für das dritte Beispiel in diesem Leitfaden würde wie folgt aussehen, wenn wir den Widgetnamen und die Größenkonfiguration aktivieren:

{
    ...
    "contributions": [
        ... , 
        {
             "id": "HelloWorldWidget3",
             "type": "ms.vss-dashboards-web.widget",
             "targets": [
                 "ms.vss-dashboards-web.widget-catalog",  "fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration"
             ],
             "properties": {
                 "name": "Hello World Widget 3 (with config)",
                 "description": "My third widget",
                 "previewImageUrl": "img/preview3.png",                       
                 "uri": "hello-world3.html",
                 "isNameConfigurable": true,
                 "supportedSizes": [
                    {
                        "rowSpan": 1,
                        "columnSpan": 2
                    },
                    {
                        "rowSpan": 2,
                        "columnSpan": 2
                    }
                 ],
                 "supportedScopes": ["project_team"]
             }
         },
         ...
}

Mit der vorherigen Änderung packen Sie Ihre Erweiterung neu, und aktualisieren Sie sie. Aktualisieren Sie das Dashboard mit diesem Widget (Hallo Welt Widget 3 (mit Konfiguration)). Öffnen Sie den Konfigurationsmodus für Ihr Widget. Sie sollten jetzt in der Lage sein, die Option zum Ändern des Widgetnamens und der Größe anzuzeigen.

Widget, in dem Name und Größe konfiguriert werden können

Wählen Sie eine andere Größe aus der Dropdownliste aus. Die Größe der Livevorschau wird geändert. Speichern Sie die Änderung, und die Größe des Widgets auf dem Dashboard wird ebenfalls geändert.

Warnung

Wenn Sie eine bereits unterstützte Größe entfernen, kann das Widget nicht ordnungsgemäß geladen werden. Wir arbeiten an einem Fix für ein zukünftiges Release.

Das Ändern des Namens des Widgets führt zu keiner sichtbaren Änderung des Widgets. Dies liegt daran, dass in unseren Beispielwidgets der Widgetname an keiner Stelle angezeigt wird. Ändern Sie den Beispielcode so, dass der Widgetname anstelle des hartcodierten Texts "Hallo Welt" angezeigt wird.

Ersetzen Sie hierzu den hartcodierten Text "Hallo Welt" widgetSettings.name durch in der Zeile, in der wir den Text des h2 Elements festlegen. Dadurch wird sichergestellt, dass der Widgetname jedes Mal angezeigt wird, wenn das Widget bei der Seitenaktualisierung geladen wird. Da die Livevorschau jedes Mal aktualisiert werden soll, wenn sich die Konfiguration ändert, sollten wir denselben Code auch im reload Teil unseres Codes hinzufügen. Die endgültige Rückgabe-Anweisung in hello-world3.html lautet wie folgt:

return {
    load: function (widgetSettings) {
        // Set your title
        var $title = $('h2.title');
        $title.text(widgetSettings.name);

        return getQueryInfo(widgetSettings);
    },
    reload: function (widgetSettings) {
        // Set your title
        var $title = $('h2.title');
        $title.text(widgetSettings.name);

        return getQueryInfo(widgetSettings);
    }
}

Packen Sie Ihre Erweiterung neu, und aktualisieren Sie sie erneut. Aktualisieren Sie das Dashboard mit diesem Widget. Bei Änderungen am Widgetnamen aktualisieren Sie im Konfigurationsmodus jetzt den Widgettitel.