Creare un provider di connessione per un'estensione della soluzione

I provider di connessione svolgono un ruolo importante nel determinare il modo in cui Windows Admin Center definisce e comunica con oggetti collegabili o destinazioni. In primo luogo, un provider di connessione esegue azioni durante l'esecuzione di una connessione, ad esempio garantisce che la destinazione sia online e disponibile e che l'utente che si connette abbia l'autorizzazione per accedere alla destinazione.

Per impostazione predefinita, Windows Admin Center viene fornito con i provider di connessione seguenti:

• Server
• Client Windows
• Cluster di failover
• Stack HCI

Per creare un provider di connessione personalizzato, seguire questa procedura:

• Aggiungere i dettagli del provider di connessione a manifest.json
• Definire il provider di stato della connessione
• Implementare il provider di connessione a livello di applicazione

Aggiungere i dettagli del provider di connessione a manifest.json

Verranno ora descritti gli elementi necessari per definire un provider di connessione nel file manifest.json del progetto.

Creare una voce in manifest.json

Il file manifest.json si trova nella cartella \src e contiene, tra le altre cose, le definizioni dei punti di ingresso del progetto. I tipi di punti di ingresso includono Strumenti, Soluzioni e Provider di connessione. Definizione di provider di connessione.

Di seguito è riportato l’esempio di una voce Provider di connessione 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"
        }
      }
    },

Un punto di ingresso di tipo "connectionProvider" indica alla shell di Windows Admin Center che l'elemento che si sta configurando è un provider che verrà usato da una soluzione per convalidare uno stato di connessione. I punti di ingresso del provider di connessione contengono una serie di proprietà importanti, definite di seguito:

Definire il provider di stato della connessione

Il provider di stato della connessione è il meccanismo in base al quale una destinazione viene convalidata per essere online e disponibile, assicurando inoltre che l'utente che si connette abbia l'autorizzazione per accedere alla destinazione. Attualmente sono disponibili due tipi di provider di stato della connessione: PowerShell e RelativeGatewayUrl.

• Provider di stato della connessione PowerShell: determina se una destinazione è online e accessibile con uno script PowerShell. Il risultato deve essere restituito in un oggetto con una singola proprietà "stato", definita di seguito.
• Provider di stato della connessione RelativeGatewayUrl: determina se una destinazione è online e accessibile con una chiamata rest. Il risultato deve essere restituito in un oggetto con una singola proprietà "stato", definita di seguito.

Definire lo stato

I provider di stato della connessione devono restituire un oggetto con una singola proprietà status conforme al formato seguente:

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

Proprietà dello stato:

• Etichetta: etichetta che descrive il tipo di stato restituito. Si noti che i valori dell'etichetta possono essere mappati in fase di esecuzione. Vedere la voce seguente per il mapping dei valori in fase di esecuzione.

• Tipo: tipo di stato restituito. Il tipo ha i valori di enumerazione seguenti. Per qualsiasi valore pari o superiore a 2, la piattaforma non passerà all'oggetto connesso e verrà mostrato un errore nell'interfaccia utente.

  Tipi:

  Valore	Descrizione
  0	Online
  1	Avviso
  2	Non autorizzata
  3	Errore
  4	Fatal
  5	Sconosciuto

• Dettagli: dettagli aggiuntivi che descrivono il tipo di stato restituito.

Script del provider di stato della connessione PowerShell

Lo script PowerShell del provider di stato della connessione determina se una destinazione è online e accessibile con uno script PowerShell. Il risultato deve essere restituito in un oggetto con una singola proprietà "stato". Di seguito è riportato uno script di esempio.

Script PowerShell di esempio:

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

Definire il metodo del provider di stato della connessione RelativeGatewayUrl

Il metodo del provider di stato della connessione RelativeGatewayUrl chiama un'API rest per determinare se una destinazione è online e accessibile. Il risultato deve essere restituito in un oggetto con una singola proprietà "stato". Di seguito è illustrato un esempio di voce del provider di connessione in manifest.json di un relativeGatewayUrl.

    {
      "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"
        }
      }
    },

Note sull'uso di RelativeGatewayUrl:

• "relativeGatewayUrl" indica dove ottenere lo stato della connessione da un URL del gateway. Questo URI è relativo a /api. Se viene trovato nell’URL $connectionName, verrà sostituito con il nome della connessione.
• Tutte le proprietà relativeGatewayUrl devono essere eseguite sul gateway host, operazione che può essere realizzata creando un'estensione del gateway

Eseguire il mapping dei valori in fase di esecuzione

I valori di etichetta e dettagli nell'oggetto di stato restituito possono essere formattati in fase di ottimizzazione includendo chiavi e valori nella proprietà "defaultValueMap" del provider.

Ad esempio, se si aggiunge il valore seguente, ogni volta che "defaultConnection_test" viene visualizzato come valore dell’etichetta o dei dettagli, Windows Admin Center sostituirà automaticamente la chiave con il valore della stringa della risorsa configurata.

    "defaultConnection_test": "resources:strings:addServer_status_defaultConnection_label"

Implementare il provider di connessione a livello di applicazione

A questo punto si implementerà il provider di connessione nel livello dell'applicazione creando una classe TypeScript che implementa OnInit. La classe ha le funzioni seguenti:

Definizione di onSubmit

onSubmit invia una chiamata RPC al contesto dell'app per notificare alla shell un tentativo di "Aggiungi connessione". La chiamata di base usa "updateData" come segue:

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

Il risultato è una proprietà di connessione, ovvero una matrice di oggetti conformi alla struttura seguente:

/**
 * 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'
};

Definizione di onCancel

onCancel annulla un tentativo di "Aggiungi connessione" passando una matrice di connessioni vuota:

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

Esempio di provider di connessione

Di seguito è riportata la classe TypeScript completa per l'implementazione di un provider di connessione. Si noti che la stringa "connectionType" corrisponde al connectionType definito nel provider di connessione in manifest.json.

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