Erstellen eines Verbindungsanbieters für eine Lösungserweiterung

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:

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.

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:

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: [] } });
  }
}