Controllare la visibilità dello strumento in una soluzione

  • Articolo

Si applica a: Windows Admin Center, Windows Admin Center Preview

In alcuni casi, potrebbe essere necessario escludere (o nascondere) l'estensione o lo strumento dall'elenco degli strumenti disponibili. Ad esempio, se lo strumento è destinato solo a Windows Server 2016 (non alle versioni precedenti), potrebbe non essere necessario che un utente che si connette a un server Windows Server 2012 R2 visualizzi lo strumento. (Si immagini l'esperienza utente: viene fatto clic, si attende il caricamento dello strumento, per poi ricevere un messaggio che indica che le funzionalità non sono disponibili per la connessione). È possibile definire quando mostrare (o nascondere) la funzionalità nel file manifest.json dello strumento.

Opzioni per decidere quando mostrare uno strumento

Sono disponibili tre diverse opzioni per determinare se lo strumento deve essere visualizzato e disponibile per uno specifico server o connessione di cluster.

  • localhost
  • inventario (una matrice di proprietà)
  • script

LocalHost

La proprietà localHost dell'oggetto Conditions contiene un valore booleano che può essere valutato per dedurre se il nodo di connessione è localHost (lo stesso computer in cui è installato Windows Admin Center) o meno. Passando un valore alla proprietà, si indica quando (la condizione) visualizzare lo strumento. Ad esempio, se si vuole che lo strumento venga visualizzato solo se l'utente si connette effettivamente all'host locale, è possibile impostarlo come segue:

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

In alternativa, se si vuole che lo strumento venga visualizzato solo quando il nodo di connessione non è localhost:

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

Ecco come appaiono le impostazioni di configurazione per mostrare uno strumento solo quando il nodo di connessione non è 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
        }
        ]
    }
    ]
}

Inventario delle proprietà

L'SDK include un set pre-curato di proprietà dell'inventario che è possibile usare per creare condizioni che determinano quando lo strumento deve essere disponibile o meno. Sono presenti nove proprietà diverse nella matrice "inventario":

Nome proprietà Tipo di valore previsto
computerManufacturer string
operatingSystemSKU number
operatingSystemVersion version_string (ad esempio: "10.1.*")
productType number
clusterFqdn string
isHyperVRoleInstalled boolean
isHyperVPowershellInstalled boolean
isManagementToolsAvailable boolean
isWmfInstalled boolean

Ogni oggetto nella matrice dell'inventario deve essere conforme alla seguente struttura json:

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

Valori dell'operatore

Operator Descrizione
gt maggiore di
ge maggiore o uguale a
lt minore di
le minore o uguale a
eq uguale a
ne diverso da
è verificare se un valore è true
not verificare se un valore è false
contiene elemento esistente in una stringa
notContains elemento non esistente in una stringa

Tipo di dati

Opzioni disponibili per la proprietà "type":

Type Description
versione un numero di versione (ad esempio: 10.1.*)
number un valore numerico
string un valore stringa
boolean true o false

Tipi di valori

La proprietà "value" accetta questi tipi:

  • string
  • number
  • boolean

Un set di condizioni di inventario correttamente formato si presenta come segue:

"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

Infine, è possibile eseguire uno script di PowerShell personalizzato per identificare la disponibilità e lo stato del nodo. Tutti gli script devono restituire un oggetto con la struttura seguente:

@{
    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 proprietà State è il valore importante che controlla la decisione di mostrare o nascondere l'estensione nell'elenco degli strumenti. I valori consentiti sono:

Valore Descrizione
Disponibile L'estensione deve essere visualizzata nell'elenco degli strumenti.
NotSupported L'estensione non deve essere visualizzata nell'elenco degli strumenti.
NotConfigured Si tratta di un valore segnaposto per un lavoro futuro che richiederà all'utente una configurazione aggiuntiva prima che lo strumento venga reso disponibile. Attualmente questo valore determina la visualizzazione dello strumento ed è l'equivalente funzionale di "Disponibile".

Ad esempio, se si vuole che uno strumento venga caricato solo se nel server remoto è installato BitLocker, lo script sarà simile al seguente:

$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

Una configurazione del punto di ingresso che usa l'opzione script è simile alla seguente:

"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"
        }
        ]
    }
    ]
}

Supporto di più set di requisiti

È possibile usare più di un set di requisiti per determinare quando visualizzare lo strumento, definendo più blocchi "requisiti".

Ad esempio, per visualizzare lo strumento se "lo scenario A" O "lo scenario B" è true, definire due blocchi di requisiti; se uno dei due è true (ovvero se tutte le condizioni all'interno di un blocco di requisiti vengono soddisfatte), lo strumento viene visualizzato.

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

Supporto degli intervalli di condizioni

È anche possibile definire un intervallo di condizioni definendo più blocchi "condizioni" con la stessa proprietà, ma con operatori diversi.

Quando la stessa proprietà viene definita con operatori diversi, lo strumento viene visualizzato finché il valore è compreso tra le due condizioni.

Ad esempio, questo strumento viene visualizzato se il sistema operativo è una versione compresa tra 6.3.0 e 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"
                }
            }
        }
        ]
    }
    ]
}