Contrôler la visibilité de votre outil dans une solution

Article
04/17/2023
S’applique à:

✅ Windows Admin Center, ✅ Windows Admin Center Preview

Il peut arriver que vous souhaitiez exclure (ou masquer) votre extension ou outil de la liste des outils disponibles. Par exemple, si votre outil cible uniquement Windows Server 2016 (et non les versions antérieures), il se peut qu’un utilisateur qui se connecte à un serveur Windows Server 2012 R2 puisse voir votre outil. (Imaginez l’expérience utilisateur : l’utilisateur clique dessus, attend que l’outil se charge pour obtenir un message indiquant que ses fonctionnalités ne sont pas disponibles pour sa connexion.) Vous pouvez définir quand afficher (ou masquer) votre fonctionnalité dans le fichier manifest.json de l’outil.

Options permettant de décider quand afficher un outil

Vous pouvez utiliser trois options différentes pour déterminer si votre outil doit être affiché et disponible pour une connexion à un serveur ou cluster spécifique.

localhost
inventaire (tableau de propriétés)
script

LocalHost

La propriété localHost de l’objet Conditions contient une valeur booléenne qui peut être évaluée pour déduire si le nœud de connexion est localHost (le même ordinateur sur lequel Windows Admin Center est installé) ou non. En attribuant une valeur à la propriété, vous indiquez quand (la condition) afficher l’outil. Par exemple, si vous souhaitez que l’outil ne s’affiche que si l’utilisateur se connecte à l’hôte local, configurez-le comme suit :

"conditions": [
{
    "localhost": true
}]

Sinon, si vous souhaitez que votre outil s’affiche uniquement lorsque le nœud de connexion n’est pas localhost :

"conditions": [
{
    "localhost": false
}]

Voici à quoi ressemblent les paramètres de configuration pour n’afficher un outil que lorsque le nœud de connexion n’est pas localhost :

"entryPoints": [
{
    "entryPointType": "tool",
    "name": "main",
    "urlName": "processes",
    "displayName": "resources:strings:displayName",
    "description": "resources:strings:description",
    "icon": "sme-icon:icon-win-serverProcesses",
    "path": "",
    "requirements": [
    {
        "solutionIds": [
        "msft.sme.server-manager!windowsClients"
        ],
        "connectionTypes": [
        "msft.sme.connection-type.windows-client"
        ],
        "conditions": [
        {
            "localhost": true
        }
        ]
    }
    ]
}

Propriétés d’inventaire

Le Kit de développement logiciel (SDK) inclut un ensemble préorganisé de propriétés d’inventaire que vous pouvez utiliser pour générer des conditions afin de déterminer quand votre outil doit être disponible ou non. Il existe neuf propriétés différentes dans le tableau « inventaire » :

Nom de la propriété	Type de valeur attendue
computerManufacturer	string
operatingSystemSKU	nombre
operatingSystemVersion	version_string (p. ex. : « 10.1.* »)
productType	nombre
clusterFqdn	string
isHyperVRoleInstalled	boolean
isHyperVPowershellInstalled	boolean
isManagementToolsAvailable	boolean
isWmfInstalled	boolean

Chaque objet du tableau d’inventaire doit être conforme à la structure json suivante :

"<property name>": {
    "type": "<expected type>",
    "operator": "<defined operator to use>",
    "value": "<expected value to evaluate using the operator>"
}

Valeurs d’opérateur

Opérateur	Description
gt	supérieur à
ge	supérieur ou égal à
lt	inférieur à
le	inférieur ou égal à
eq	égal à
ne	différent de
is	vérifier si une valeur est vraie
not	vérifier si une valeur est fausse
contains	l’élément existe dans une chaîne
notContains	l’élément n’existe pas dans une chaîne

Types de données

Options disponibles pour la propriété « type » :

Type	Description
version	numéro de version (p. ex. : 10.1.*)
nombre	valeur numérique
string	valeur de chaîne
boolean	True ou False

Types de valeur

La propriété « value » accepte les types suivants :

chaîne
nombre
boolean

Un jeu de conditions d’inventaire correctement formé ressemble à ceci :

"entryPoints": [
{
    "entryPointType": "tool",
    "name": "main",
    "urlName": "processes",
    "displayName": "resources:strings:displayName",
    "description": "resources:strings:description",
    "icon": "sme-icon:icon-win-serverProcesses",
    "path": "",
    "requirements": [
    {
        "solutionIds": [
        "msft.sme.server-manager!servers"
        ],
        "connectionTypes": [
        "msft.sme.connection-type.server"
        ],
        "conditions": [
        {
            "inventory": {
            "operatingSystemVersion": {
                "type": "version",
                "operator": "gt",
                "value": "6.3"
            },
            "operatingSystemSKU": {
                "type": "number",
                "operator": "eq",
                "value": "8"
            }
            }
        }
        ]
    }
    ]
}

Script

Enfin, vous pouvez exécuter un script PowerShell personnalisé pour identifier la disponibilité et l’état du nœud. Tous les scripts doivent retourner un objet avec la structure suivante :

@{
    State = 'Available' | 'NotSupported' | 'NotConfigured';
    Message = '<Message to explain the reason of state such as not supported and not configured.>';
    Properties =
        @{ Name = 'Prop1'; Value = 'prop1 data'; Type = 'string' },
        @{Name='Prop2'; Value = 12345678; Type='number'; };
}

La propriété State est la valeur importante qui contrôlera la décision d’afficher ou de masquer votre extension dans la liste des outils. Les valeurs autorisées sont les suivantes :

Valeur	Description
Disponible	L’extension doit être affichée dans la liste des outils.
NotSupported	L’extension ne doit pas être affichée dans la liste des outils.
NotConfigured	Il s’agit d’une valeur d’espace réservé pour les travaux futurs qui invitera l’utilisateur à effectuer une configuration supplémentaire avant que l’outil ne soit mis à disposition. Actuellement, cette valeur entraîne l’affichage de l’outil et est l’équivalent fonctionnel de « Disponible ».

Par exemple, si nous voulons qu’un outil se charge uniquement si BitLocker est installé sur le serveur distant, le script se présente comme suit :

$response = @{
    State = 'NotSupported';
    Message = 'Not executed';
    Properties = @{ Name = 'Prop1'; Value = 'prop1 data'; Type = 'string' },
        @{Name='Prop2'; Value = 12345678; Type='number'; };
}

if (Get-Module -ListAvailable -Name servermanager) {
    Import-module servermanager;
    $isInstalled = (Get-WindowsFeature -name bitlocker).Installed;
    $isGood = $isInstalled;
}

if($isGood) {
    $response.State = 'Available';
    $response.Message = 'Everything should work.';
}

$response

La configuration du point d’entrée à l’aide de l’option de script ressemble à ceci :

"entryPoints": [
{
    "entryPointType": "tool",
    "name": "main",
    "urlName": "processes",
    "displayName": "resources:strings:displayName",
    "description": "resources:strings:description",
    "icon": "sme-icon:icon-win-serverProcesses",
    "path": "",
    "requirements": [
    {
        "solutionIds": [
        "msft.sme.server-manager!windowsClients"
        ],
        "connectionTypes": [
        "msft.sme.connection-type.windows-client"
        ],
        "conditions": [
        {
            "localhost": true,
            "inventory": {
            "operatingSystemVersion": {
                "type": "version",
                "operator": "eq",
                "value": "10.0.*"
            },
            "operatingSystemSKU": {
                "type": "number",
                "operator": "eq",
                "value": "4"
            }
            },
            "script": "$response = @{ State = 'NotSupported'; Message = 'Not executed'; Properties = @{ Name = 'Prop1'; Value = 'prop1 data'; Type = 'string' }, @{Name='Prop2'; Value = 12345678; Type='number'; }; }; if (Get-Module -ListAvailable -Name servermanager) { Import-module servermanager; $isInstalled = (Get-WindowsFeature -name bitlocker).Installed; $isGood = $isInstalled; }; if($isGood) { $response.State = 'Available'; $response.Message = 'Everything should work.'; }; $response"
        }
        ]
    }
    ]
}

Prise en charge de plusieurs ensembles de conditions requises

Vous pouvez utiliser plusieurs ensembles de conditions requises pour déterminer quand afficher votre outil en définissant plusieurs blocs « de conditions requises ».

Par exemple, pour afficher votre outil si le « scénario A » OU le « scénario B » est vrai, définissez deux blocs de conditions requises ; si l’un ou l’autre est vrai (c’est-à-dire si toutes les conditions d’un bloc de conditions requises sont remplies), l’outil s’affiche.

"entryPoints": [
{
    "requirements": [
    {
        "solutionIds": [
            …"scenario A"…
        ],
        "connectionTypes": [
            …"scenario A"…
        ],
        "conditions": [
            …"scenario A"…
        ]
    },
    {
        "solutionIds": [
            …"scenario B"…
        ],
        "connectionTypes": [
            …"scenario B"…
        ],
        "conditions": [
            …"scenario B"…
        ]
    }
    ]
}

Prise en charge de plages de conditions

Vous pouvez également définir une plage de conditions en définissant plusieurs blocs « conditions » avec la même propriété, mais avec des opérateurs différents.

Lorsque la même propriété est définie avec des opérateurs différents, l’outil s’affiche tant que la valeur se trouve entre les deux conditions.

Par exemple, cet outil s’affiche tant que la version du système d’exploitation est comprise entre 6.3.0 et 10.0.0 :

"entryPoints": [
{
    "entryPointType": "tool",
    "name": "main",
    "urlName": "processes",
    "displayName": "resources:strings:displayName",
    "description": "resources:strings:description",
    "icon": "sme-icon:icon-win-serverProcesses",
    "path": "",
    "requirements": [
    {
        "solutionIds": [
             "msft.sme.server-manager!servers"
        ],
        "connectionTypes": [
             "msft.sme.connection-type.server"
        ],
        "conditions": [
        {
            "inventory": {
                "operatingSystemVersion": {
                    "type": "version",
                    "operator": "gt",
                    "value": "6.3.0"
                },
            }
        },
        {
            "inventory": {
                "operatingSystemVersion": {
                    "type": "version",
                    "operator": "lt",
                    "value": "10.0.0"
                }
            }
        }
        ]
    }
    ]
}

Partager via