Controllare la visibilità dello strumento in una soluzione

Articolo
02/23/2024
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"
                }
            }
        }
        ]
    }
    ]
}

Condividi tramite