Erstellen eines Verbindungsanbieters für eine Lösungserweiterung

Artikel
04/10/2023
Gilt für::

✅ Windows Admin Center, ✅ Windows Admin Center Preview

Verbindungsanbieter spielen eine wichtige Rolle bei der Definition und Kommunikation mit verbindungsfähigen Objekten oder Zielen durch Windows Admin Center. In erster Linie führt ein Verbindungsanbieter Aktionen aus, während eine Verbindung hergestellt wird. Er stellt z. B. sicher, dass das Ziel online und verfügbar ist und dass der Benutzer, der die Verbindung herstellt, über Zugriffsberechtigung für das Ziel verfügt.

Standardmäßig sind die folgenden Verbindungsanbieter im Lieferumfang von Windows Admin Center enthalten:

Server
Windows-Client
Failovercluster
HCI-Cluster

Führen Sie die folgenden Schritte aus, um einen eigenen benutzerdefinierten Verbindungsanbieter zu erstellen:

Hinzufügen von Verbindungsanbieterdetails zu manifest.json
Definieren des Verbindungsstatusanbieters
Implementieren des Verbindungsanbieters in der Anwendungsschicht

Hinzufügen von Verbindungsanbieterdetails zu „manifest.json“

Nun erfahren Sie, was Sie wissen müssen, um einen Verbindungsanbieter in der manifest.json-Datei Ihres Projekts zu definieren.

Erstellen eines Eintrags in manifest.json

Die manifest.json-Datei befindet sich im Ordner „\src“ und enthält unter anderem Definitionen von Einstiegspunkten in Ihr Projekt. Zu den Einstiegspunkten gehören Tools, Lösungen und Verbindungsanbieter. Wir definieren einen Verbindungsanbieter.

Nachfolgend finden Sie ein Beispiel für einen Verbindungsanbietereintrag in manifest.json:

    {
      "entryPointType": "connectionProvider",
      "name": "addServer",
      "path": "/add",
      "displayName": "resources:strings:addServer_displayName",
      "icon": "sme-icon:icon-win-server",
      "description": "resources:strings:description",
      "connectionType": "msft.sme.connection-type.server",
      "connectionTypeName": "resources:strings:addServer_connectionTypeName",
      "connectionTypeUrlName": "server",
      "connectionTypeDefaultSolution": "msft.sme.server-manager!servers",
      "connectionTypeDefaultTool": "msft.sme.server-manager!overview",
      "connectionStatusProvider": {
        "powerShell": {
          "script": "## Get-My-Status ##\nfunction Get-Status()\n{\n# A function like this would be where logic would exist to identify if a node is connectable.\n$status = @{label = $null; type = 0; details = $null; }\n$caption = \"MyConstCaption\"\n$productType = \"MyProductType\"\n# A result object needs to conform to the following object structure to be interpreted properly by the Windows Admin Center shell.\n$result = @{ status = $status; caption = $caption; productType = $productType; version = $version }\n# DO FANCY LOGIC #\n# Once the logic is complete, the following fields need to be populated:\n$status.label = \"Display Thing\"\n$status.type = 0 # This value needs to conform to the LiveConnectionStatusType enum. >= 3 represents a failure.\n$status.details = \"success stuff\"\nreturn $result}\nGet-Status"
        },
        "displayValueMap": {
          "wmfMissing-label": "resources:strings:addServer_status_wmfMissing_label",
          "wmfMissing-details": "resources:strings:addServer_status_wmfMissing_details",
          "unsupported-label": "resources:strings:addServer_status_unsupported_label",
          "unsupported-details": "resources:strings:addServer_status_unsupported_details"
        }
      }
    },

Ein Einstiegspunkt vom Typ „connnectionProvider“ teilt der Windows Admin Center-Shell mit, dass das konfigurierte Element ein Anbieter ist, der von einer Lösung zum Überprüfen des Verbindungsstatus verwendet wird. Einstiegspunkte für Verbindungsanbieter enthalten eine Reihe wichtiger Eigenschaften, die nachstehend definiert werden:

Eigenschaft	Beschreibung
entryPointType	Dies ist eine erforderliche Eigenschaft. Es gibt drei gültige Werte: „tool“, „solution“ und „connectionProvider“.
name	Gibt den Verbindungsanbieter im Bereich einer Lösung an. Dieser Wert muss innerhalb einer vollständigen Windows Admin Center-Instanz (nicht nur einer Lösung) eindeutig sein.
path	Stellt den URL-Pfad für die Benutzeroberfläche zum Hinzufügen einer Verbindung dar, sofern die Konfiguration durch die Lösung erfolgt. Dieser Wert muss einer Route zugeordnet werden, die in der Datei „app-routing.module.ts“ konfiguriert ist. Wenn für den Lösungseinstiegspunkt die Verwendung von „rootNavigationBehavior“ für Verbindungen konfiguriert ist, lädt diese Route das Modul, das von der Shell zum Anzeigen der Benutzeroberfläche zum Hinzufügen von Verbindungen verwendet wird. Weitere Informationen finden Sie im Abschnitt zu „rootNavigationBehavior“.
displayName	Der hier eingegebene Wert wird auf der rechten Seite der Shell unter der schwarzen Windows Admin Center-Leiste angezeigt, wenn ein Benutzer die Verbindungsseite einer Lösung lädt.
icon	Stellt das Symbol dar, das im Dropdownmenü für Lösungen verwendet wird, um die Lösung darzustellen.
description	Geben Sie eine kurze Beschreibung des Einstiegspunkts ein.
connectionType	Stellt den Verbindungstyp dar, den der Anbieter lädt. Der hier eingegebene Wert wird auch im Lösungseinstiegspunkt verwendet, um anzugeben, dass die Lösung diese Verbindungen laden kann. Der hier eingegebene Wert wird auch in den Tooleinstiegspunkten verwendet, um anzugeben, dass das Tool mit diesem Typ kompatibel ist. Der hier eingegebene Wert wird auch im Verbindungsobjekt verwendet, das im Implementierungsschritt der Anwendungsschicht an den RPC-Aufruf von „Add window“ übermittelt wird.
connectionTypeName	Wird in der Verbindungstabelle verwendet, um eine Verbindung darzustellen, die Ihren Verbindungsanbieter verwendet. Hier wird der Pluralname des Typs erwartet.
connectionTypeUrlName	Wird beim Erstellen der URL verwendet, um die geladene Lösung darzustellen, nachdem Windows Admin Center eine Verbindung zu einer Instanz hergestellt hat. Dieser Eintrag wird nach Verbindungen und vor dem Ziel verwendet. Im folgenden Beispiel wird dieser Wert als mit „connectionexample“ in der URL angezeigt: `http://localhost:6516/solutionexample/connections/connectionexample/con-fake1.corp.contoso.com`
connectionTypeDefaultSolution	Stellt die Standardkomponente dar, die vom Verbindungsanbieter geladen werden soll. Dieser Wert ist eine Kombination von: [a] Name des Erweiterungspakets, das am Anfang des Manifests definiert wird [b] Ausrufezeichen (!) [c] Name des Lösungseinstiegspunkts Bei einem Projekt mit dem Namen „msft.sme.mySample-extension“ und einem Lösungseinstiegspunkt mit dem Namen „example“ lautet dieser Wert „msft.sme.solutionExample-extension!example“.
connectionTypeDefaultTool	Stellt das Standardtool dar, das bei einer erfolgreichen Verbindungsherstellung geladen werden soll. Dieser Eigenschaftswert besteht ähnlich wie „connectionTypeDefaultSolution“ aus zwei Teilen. Dieser Wert ist eine Kombination von: [a] Name des Erweiterungspakets, das am Anfang des Manifests definiert wird [b] Ausrufezeichen (!) [c] Name des Tooleinstiegspunkts für das Tool, das zunächst geladen werden soll Bei einem Projekt mit dem Namen „msft.sme.solutionExample-extension“ und einem Lösungseinstiegspunkt mit dem Namen „example“ lautet dieser Wert „msft.sme.solutionExample-extension!example“.
connectionStatusProvider	Weitere Informationen hierzu finden Sie im Abschnitt „Definieren des Verbindungsstatusanbieters“.

Definieren des Verbindungsstatusanbieters

Der Verbindungsstatusanbieter ist der Mechanismus, mit dem überprüft wird, ob ein Ziel online und verfügbar ist, um sicherzustellen, dass der Benutzer, der die Verbindung herstellt, über Zugriffsberechtigung für das Ziel verfügt. Derzeit gibt es zwei verschiedenartige Verbindungsstatusanbieter: PowerShell und RelativeGatewayUrl.

PowerShell-Verbindungsstatusanbieter: Ermittelt, ob ein Ziel online und mit einem PowerShell-Skript erreichbar ist. Das Ergebnis muss in einem Objekt mit einer einzelnen „status“-Eigenschaft zurückgegeben werden (siehe Definition weiter unten).
RelativeGatewayUrl-Verbindungsstatusanbieter: Ermittelt, ob ein Ziel online und mit einem REST-Aufruf erreichbar ist. Das Ergebnis muss in einem Objekt mit einer einzelnen „status“-Eigenschaft zurückgegeben werden (siehe Definition weiter unten).

Definieren des Status

Verbindungsstatusanbieter müssen ein Objekt mit einer einzelnen status-Eigenschaft mit dem folgenden Format zurückgeben:

{
    status: {
        label: string;
        type: int;
        details: string;
    }
}

Statuseigenschaften:

Label: Eine Bezeichnung, die den status-Rückgabetyp beschreibt. Die Werte für „label“ können zur Laufzeit zugeordnet werden. Informationen zur Zuordnung von Werten zur Laufzeit finden Sie im folgenden Eintrag.
Type: Der status-Rückgabetyp. „Type“ umfasst die folgenden Enumerationswerte. Für jeden Wert größer-gleich 2 navigiert die Plattform nicht zum verbundenen Objekt, und auf der Benutzeroberfläche wird ein Fehler angezeigt.

Typen:

Wert Beschreibung

0 Online

1 Warnung

2 Nicht autorisiert

3 Fehler

4 Schwerwiegend

5 Unbekannt
Details: Zusätzliche Details, die den status-Rückgabetyp beschreiben.

Wert	Beschreibung
0	Online
1	Warnung
2	Nicht autorisiert
3	Fehler
4	Schwerwiegend
5	Unbekannt

Skript für den PowerShell-Verbindungsstatusanbieter

Das Skript für den PowerShell-Verbindungsstatusanbieter ermittelt, ob ein Ziel online und mit einem PowerShell-Skript erreichbar ist. Das Ergebnis muss in einem Objekt mit einer einzelnen „status“-Eigenschaft zurückgegeben werden. Nachstehend finden Sie ein Beispielskript.

PowerShell-Beispielskript:

## Get-My-Status ##

function Get-Status()
{
    # A function like this would be where logic would exist to identify if a node is connectable.
    $status = @{label = $null; type = 0; details = $null; }
    $caption = "MyConstCaption"
    $productType = "MyProductType"

    # A result object needs to conform to the following object structure to be interperated properly by the Windows Admin Center shell.
    $result = @{ status = $status; caption = $caption; productType = $productType; version = $version }

    # DO FANCY LOGIC #

    # Once the logic is complete, the following fields need to be populated:
    $status.label = "Display Thing"
    $status.type = 0 # This value needs to conform to the LiveConnectionStatusType enum. >= 3 represents a failure.
    $status.details = "success stuff"

    return $result
}

Get-Status

Definieren der Methode für den RelativeGatewayUrl-Verbindungsstatusanbieter

Die Methode des RelativeGatewayUrl-Verbindungsstatusanbieters ruft eine REST-API auf, um zu ermitteln, ob ein Ziel online und erreichbar ist. Das Ergebnis muss in einem Objekt mit einer einzelnen „status“-Eigenschaft zurückgegeben werden. Ein Beispiel für einen Verbindungsanbietereintrag in „manifest.json“ eines RelativeGatewayUrl-Verbindungsstatusanbieters ist unten dargestellt.

    {
      "entryPointType": "connectionProvider",
      "name": "addServer",
      "path": "/add/server",
      "displayName": "resources:strings:addServer_displayName",
      "icon": "sme-icon:icon-win-server",
      "description": "resources:strings:description",
      "connectionType": "msft.sme.connection-type.server",
      "connectionTypeName": "resources:strings:addServer_connectionTypeName",
      "connectionTypeUrlName": "server",
      "connectionTypeDefaultSolution": "msft.sme.server-manager!servers",
      "connectionTypeDefaultTool": "msft.sme.server-manager!overview",
      "connectionStatusProvider": {
        "relativeGatewayUrl": "<URL here post /api>",
        "displayValueMap": {
          "wmfMissing-label": "resources:strings:addServer_status_wmfMissing_label",
          "wmfMissing-details": "resources:strings:addServer_status_wmfMissing_details",
          "unsupported-label": "resources:strings:addServer_status_unsupported_label",
          "unsupported-details": "resources:strings:addServer_status_unsupported_details"
        }
      }
    },

Hinweise zur Verwendung von „relativeGatewayUrl“:

„relativeGatewayUrl“ gibt an, wo der Verbindungsstatus aus einer Gateway-URL abgerufen werden soll. Dieser URI ist relativ zu „/api“. Wenn $connectionName in der URL vorhanden, wird dieser durch den Namen der Verbindung ersetzt.
Alle relativeGatewayUrl-Eigenschaften müssen für das Hostgateway ausgeführt werden. Dies kann durch Erstellen einer Gatewayerweiterung erreicht werden.

Zuordnen von Werten zur Laufzeit

Die label- und details-Werte im status-Rückgabeobjekt können zur Laufzeit formatiert werden, indem Schlüssel und Werte in die Eigenschaft „defaultValueMap“ des Anbieters eingefügt werden.

Wenn Sie beispielsweise den folgenden Wert hinzufügen, ersetzt Windows Admin Center automatisch den Schlüssel durch den konfigurierten Ressourcenzeichenfolgenwert, wenn „defaultConnection_test“ als Wert für „label“ oder „details“ angezeigt wird.

    "defaultConnection_test": "resources:strings:addServer_status_defaultConnection_label"

Implementieren des Verbindungsanbieters in der Anwendungsschicht

Nun implementieren wir den Verbindungsanbieter in der Anwendungsschicht, indem wir eine TypeScript-Klasse erstellen, die „OnInit“ implementiert. Die Klasse umfasst die folgenden Funktionen:

Funktion	Beschreibung
constructor(private appContextService: AppContextService, private route: ActivatedRoute)
public ngOnInit()
public onSubmit()	Enthält Logik zum Aktualisieren der Shell, wenn versucht wird, eine Verbindung hinzuzufügen.
public onCancel()	Enthält Logik zum Aktualisieren der Shell, wenn der Versuch, eine Verbindung hinzuzufügen, abgebrochen wird.

Definieren von „onSubmit“

onSubmit gibt einen RPC-Rückruf an den App-Kontext aus, um die Shell über das Hinzufügen einer Verbindung zu informieren. Der grundlegende Aufruf verwendet „updateData“ wie folgt:

this.appContextService.rpc.updateData(
    EnvironmentModule.nameOfShell,
    '##',
    <RpcUpdateData>{
        results: {
            connections: connections,
            credentials: this.useCredentials ? this.creds : null
        }
    }
);

Das Ergebnis ist eine Verbindungseigenschaft, bei der es sich um ein Array von Objekten mit der folgenden Struktur handelt:


/**
 * The connection attributes class.
 */
export interface ConnectionAttribute {

    /**
     * The id string of this attribute
     */
    id: string;

    /**
     * The value of the attribute. used for attributes that can have variable values such as Operating System
     */
    value?: string | number;
}

/**
 * The connection class.
 */
export interface Connection {

    /**
     * The id of the connection, this is unique per connection
     */
    id: string;

    /**
     * The type of connection
     */
    type: string;

    /**
     * The name of the connection, this is unique per connection type
     */
    name: string;

    /**
     * The property bag of the connection
     */
    properties?: ConnectionProperties;

    /**
     * The ids of attributes identified for this connection
     */
    attributes?: ConnectionAttribute[];

    /**
     * The tags the user(s) have assigned to this connection
     */
    tags?: string[];
}

/**
 * Defines connection type strings known by core
 * Be careful that these strings match what is defined by the manifest of @msft-sme/server-manager
 */
export const connectionTypeConstants = {
    server: 'msft.sme.connection-type.server',
    cluster: 'msft.sme.connection-type.cluster',
    hyperConvergedCluster: 'msft.sme.connection-type.hyper-converged-cluster',
    windowsClient: 'msft.sme.connection-type.windows-client',
    clusterNodesProperty: 'nodes'
};

Definieren von „onCancel“

onCancel bricht einen Versuch zum Hinzufügen einer Verbindung ab, indem ein leeres Verbindungsarray übergeben wird:

this.appContextService.rpc.updateData(EnvironmentModule.nameOfShell, '##', <RpcUpdateData>{ results: { connections: [] } });

Beispiel für einen Verbindungsanbieter

Nachstehend finden Sie die vollständige TypeScript-Klasse zum Implementieren eines Verbindungsanbieters. Beachten Sie, dass die connectionType-Zeichenfolge mit der connectionType-Definition für den Verbindungsanbieter in „manifest.json“ übereinstimmt.

import { Component, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { AppContextService } from '@microsoft/windows-admin-center-sdk/shell/angular';
import { Connection, ConnectionUtility } from '@microsoft/windows-admin-center-sdk/shell/core';
import { EnvironmentModule } from '@microsoft/windows-admin-center-sdk/shell/dist/core/manifest/environment-modules';
import { RpcUpdateData } from '@microsoft/windows-admin-center-sdk/shell/dist/core/rpc/rpc-base';
import { Strings } from '../../generated/strings';

@Component({
  selector: 'add-example',
  templateUrl: './add-example.component.html',
  styleUrls: ['./add-example.component.css']
})
export class AddExampleComponent implements OnInit {
  public newConnectionName: string;
  public strings = MsftSme.resourcesStrings<Strings>().SolutionExample;
  private connectionType = 'msft.sme.connection-type.example'; // This needs to match the connectionTypes value used in the manifest.json.

  constructor(private appContextService: AppContextService, private route: ActivatedRoute) {
    // TODO:
  }

  public ngOnInit() {
    // TODO
  }

  public onSubmit() {
    let connections: Connection[] = [];

    let connection = <Connection> {
      id: ConnectionUtility.createConnectionId(this.connectionType, this.newConnectionName),
      type: this.connectionType,
      name: this.newConnectionName
    };

    connections.push(connection);

    this.appContextService.rpc.updateData(
      EnvironmentModule.nameOfShell,
      '##',
      <RpcUpdateData> {
        results: {
          connections: connections,
          credentials: null
        }
      }
    );
  }

  public onCancel() {
    this.appContextService.rpc.updateData(
      EnvironmentModule.nameOfShell, '##', <RpcUpdateData>{ results: { connections: [] } });
  }
}

Freigeben über