Créer un fournisseur de connexion pour une extension de solution

Article
03/09/2023
S’applique à:

✅ Windows Admin Center, ✅ Windows Admin Center Preview

Les fournisseurs de connexion jouent un rôle important dans la façon dont Windows Admin Center définit et communique avec des objets ou des cibles connectables. Principalement, un fournisseur de connexion effectue des actions pendant qu’une connexion est établie, comme s’assurer que la cible est en ligne et disponible, et s’assurer que l’utilisateur qui se connecte a l’autorisation d’accéder à la cible.

Par défaut, Windows Admin Center est fourni avec les fournisseurs de connexion suivants :

Serveur
Client Windows
Cluster de basculement
Cluster HCI

Pour créer votre propre fournisseur de connexion personnalisé, procédez comme suit :

Ajouter les détails du fournisseur de connexion à manifest.json
Définir le fournisseur d’état de connexion
Implémenter le fournisseur de connexion dans la couche Application

Ajouter les détails du fournisseur de connexion à manifest.json

Nous allons maintenant passer en revue ce que vous devez savoir pour définir un fournisseur de connexion dans le fichier manifest.json de votre projet.

Créer une entrée dans manifest.json

Le fichier manifest.jsonse trouve dans le dossier \src et contient, entre autres, des définitions de points d’entrée dans votre projet. Les types de points d’entrée incluent outils, solutions et fournisseurs de connexion. Nous allons définir un fournisseur de connexion.

Voici un exemple d’entrée fournisseur de connexion dans 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 point d’entrée de type « connnectionProvider » indique à l’interpréteur de commandes Windows Admin Center que l’élément en cours de configuration est un fournisseur qui sera utilisé par une solution pour valider un état de connexion. Les points d’entrée du fournisseur de connexion contiennent un certain nombre de propriétés importantes, définies ci-dessous :

Propriété	Description
entryPointType	Cette propriété est obligatoire. Il existe trois valeurs valides : « tool », « solution » et « connectionProvider ».
name	Identifie le fournisseur de connexion dans l’étendue d’une solution. Cette valeur doit être unique à l’intérieur d’une instance Windows Admin Center complète (pas seulement une solution).
path	Représente le chemin d’URL de l’interface utilisateur « Ajouter une connexion », si elle est configurée par la solution. Cette valeur doit être mappée à un itinéraire configuré dans le fichier app-routing.module.ts. Lorsque le point d’entrée de la solution est configuré pour utiliser les connexions rootNavigationBehavior, cet itinéraire charge le module utilisé par l’interpréteur de commandes pour afficher l’interface utilisateur Ajouter une connexion. Plus d’informations sont disponibles dans la section sur rootNavigationBehavior.
displayName	La valeur entrée ici s’affiche sur le côté droit de l’interpréteur de commandes, sous la barre de Windows Admin Center noire lorsqu’un utilisateur charge la page de connexions d’une solution.
icon	Représente l’icône utilisée dans le menu déroulant Solutions pour représenter la solution.
description	Entrez une brève description du point d’entrée.
connectionType	Représente le type de connexion que le fournisseur va charger. La valeur entrée ici sera également utilisée dans le point d’entrée de la solution pour spécifier que la solution peut charger ces connexions. La valeur entrée ici sera également utilisée dans le ou les points d’entrée de l’outil pour indiquer que l’outil est compatible avec ce type. Cette valeur entrée ici sera également utilisée dans l’objet de connexion soumis à l’appel RPC sur la « fenêtre Ajouter », à l’étape d’implémentation de la couche Application.
connectionTypeName	Utilisé dans la table connections pour représenter une connexion qui utilise votre fournisseur de connexion. Il s’agit normalement du nom pluriel du type.
connectionTypeUrlName	Utilisé lors de la création de l’URL pour représenter la solution chargée, une fois Windows Admin Center s’est connecté à une instance. Cette entrée est utilisée après les connexions et avant la cible. Dans cet exemple, « connectionexample » est l’emplacement où cette valeur apparaît dans l’URL : `http://localhost:6516/solutionexample/connections/connectionexample/con-fake1.corp.contoso.com`
connectionTypeDefaultSolution	Représente le composant par défaut qui doit être chargé par le fournisseur de connexion. Cette valeur est une combinaison des éléments suivants : [a] Nom du package d’extension défini en haut du manifeste ; [b] Le point d'exclamation (!) ; [c] Nom du point d’entrée de la solution. Pour un projet avec le nom « msft.sme.mySample-extension » et un point d’entrée de solution avec le nom « example », cette valeur serait « msft.sme.solutionExample-extension!example ».
connectionTypeDefaultTool	Représente l’outil par défaut qui doit être chargé lors d’une connexion réussie. Cette valeur de propriété est composée de deux parties, similaires à connectionTypeDefaultSolution. Cette valeur est une combinaison des éléments suivants : [a] Nom du package d’extension défini en haut du manifeste ; [b] Le point d'exclamation (!) ; [c] Nom du point d’entrée de l’outil qui doit être chargé initialement. Pour un projet portant le nom « msft.sme.solutionExample-extension » et un point d’entrée de solution avec le nom « example », cette valeur est « msft.sme.solutionExample-extension!example ».
connectionStatusProvider	Consultez la section « Définir le fournisseur d’état de connexion »

Définir le fournisseur d’état de connexion

Le fournisseur d’état de connexion est le mécanisme par lequel une cible est validée pour être en ligne et disponible, garantissant également que l’utilisateur qui se connecte a l’autorisation d’accéder à la cible. Il existe actuellement deux types de fournisseurs d’état de connexion : PowerShell et RelativeGatewayUrl.

Fournisseur d’état de connexion PowerShell : détermine si une cible est en ligne et accessible avec un script PowerShell. Le résultat doit être retourné dans un objet avec une propriété unique « status », définie ci-dessous.
Fournisseur d’état de connexion RelativeGatewayUrl : détermine si une cible est en ligne et accessible à l’aide d’un appel Rest. Le résultat doit être retourné dans un objet avec une propriété unique « status », définie ci-dessous.

Définir l’État

Les fournisseurs d’état de connexion sont requis pour retourner un objet avec une propriété unique status conforme au format suivant :

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

Propriétés d’état :

Étiquette : étiquette décrivant le type de retour d’état. Notez que les valeurs d’étiquette peuvent être mappées dans l’exécution. Consultez l’entrée ci-dessous pour connaître les valeurs de mappage dans l’exécution.
Type : type de retour d’état. Type a les valeurs d’énumération suivantes. Pour toute valeur 2 ou supérieure, la plateforme n’accède pas à l’objet connecté et une erreur s’affiche dans l’interface utilisateur.

Types :

Valeur Description

0 En ligne

1 Warning

2 Non autorisé

3 Error

4 Erreur irrécupérable

5 Unknown
Détails : détails supplémentaires décrivant le type de retour d’état.

Valeur	Description
0	En ligne
1	Warning
2	Non autorisé
3	Error
4	Erreur irrécupérable
5	Unknown

Script du fournisseur d’état de connexion PowerShell

Le script PowerShell du fournisseur d’état de connexion détermine si une cible est en ligne et accessible à l’aide d’un script PowerShell. Le résultat doit être retourné dans un objet avec une propriété unique « Status ». Vous trouverez ci-dessous un exemple de script.

Exemple de script PowerShell :

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

Définir la méthode fournisseur d’état de connexion RelativeGatewayUrl

La méthode Fournisseur d’état de connexionRelativeGatewayUrl appelle une API rest pour déterminer si une cible est en ligne et accessible. Le résultat doit être retourné dans un objet avec une propriété unique « Status ». Un exemple d’entrée fournisseur de connexion dans manifest.json d’un RelativeGatewayUrl est illustré ci-dessous.

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

Remarques sur l’utilisation de RelativeGatewayUrl :

« relativeGatewayUrl » spécifie où obtenir l’état de la connexion à partir d’une URL de passerelle. Cet URI est relatif à partir de /api. Si $connectionName est trouvé dans l’URL, elle est remplacée par le nom de la connexion.
Toutes les propriétés relativeGatewayUrl doivent être exécutées sur la passerelle hôte, ce qui peut être réalisé en créant une extension de passerelle

Mapper des valeurs dans le runtime

Les valeurs d’étiquette et de détails de l’objet de retour d’état peuvent être mises en forme au moment de l’optimisation en incluant les clés et les valeurs dans la propriété « defaultValueMap » du fournisseur.

Par exemple, si vous ajoutez la valeur ci-dessous, chaque fois que « defaultConnection_test » s’affiche en tant que valeur pour l’étiquette ou les détails, Windows Admin Center remplacera automatiquement la clé par la valeur de chaîne de ressource configurée.

    "defaultConnection_test": "resources:strings:addServer_status_defaultConnection_label"

Implémenter le fournisseur de connexion dans la couche Application

Nous allons maintenant implémenter le fournisseur de connexion dans la couche application, en créant une classe TypeScript qui implémente OnInit. La classe possède les fonctions suivantes :

Fonction	Description
constructeur(private appContextService : AppContextService, itinéraire privé : ActivatedRoute)
public ngOnInit()
public onSubmit()	Contient la logique de mise à jour de l’interpréteur de commandes lorsqu’une tentative d’ajout de connexion est effectuée
public onCancel()	Contient la logique de mise à jour de l’interpréteur de commandes lorsqu’une tentative d’ajout de connexion est annulée

Définir onSubmit

onSubmit émet un rappel RPC au contexte de l’application pour notifier l’interpréteur de commandes d’une « Ajouter une connexion ». L’appel de base utilise « updateData » comme suit :

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

Le résultat est une propriété de connexion, qui est un tableau d’objets conformes à la structure suivante :


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

Définir onCancel

onCancel annule une tentative « Ajouter une connexion » en passant un tableau de connexions vide :

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

Exemple de fournisseur de connexion

La classe TypeScript complète pour l’implémentation d’un fournisseur de connexion est ci-dessous. Notez que la chaîne « connectionType » correspond au « connectionType tel que défini dans le fournisseur de connexion dans 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: [] } });
  }
}

Partager via