Steuern der Sichtbarkeit Ihres Tools in einer Lösung

Artikel
03/09/2023

Gilt für: Windows Admin Center, Windows Admin Center-Vorschau

Es kann vorkommen, dass Sie Ihre Erweiterung oder Ihr Tool aus der Liste der verfügbaren Tools ausschließen (oder ausblenden) möchten. Wurde Ihr Tool beispielsweise nur für Windows Server 2016 (nicht für ältere Versionen) konzipiert, soll es möglicherweise Benutzer*innen, die eine Verbindung mit einem Windows Server 2012 R2-Server herstellen, gar nicht angezeigt werden. (Andernfalls würde Benutzer*innen, die darauf klicken und warten, bis das Tool geladen wird, die Meldung angezeigt, dass die Features für ihre Verbindung nicht verfügbar sind.) Sie können definieren, wann Ihr Feature in der Datei „manifest.json“ des Tools angezeigt (oder ausgeblendet) werden soll.

Optionen für die Entscheidung zur Anzeige eines Tools

Sie haben drei Optionen für die Entscheidung, ob Ihr Tool angezeigt und für eine bestimmte Server- oder Clusterverbindung verfügbar sein soll.

localhost
Inventory (ein Array von Eigenschaften)
script

LocalHost

Die localHost-Eigenschaft des Conditions-Objekts enthält einen booleschen Wert, aus dem abgeleitet werden kann, ob es sich bei dem Verbindungsknoten um „localHost“ handelt (dem Computer, auf dem Windows Admin Center installiert ist). Durch Übergabe eines Werts an die Eigenschaft geben Sie an, wann das Tool angezeigt werden soll (die Bedingung). Soll das Tool beispielsweise nur angezeigt werden, wenn die Benutzer*innen tatsächlich eine Verbindung mit dem lokalen Host herstellen, verwenden Sie folgende Angabe:

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

Soll Ihr Tool dagegen nur angezeigt werden, wenn es sich bei dem Verbindungsknoten nicht um „localhost“ handelt, verwenden Sie folgende Angabe:

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

Mit den folgenden Konfigurationseinstellungen wird das Tool nur angezeigt, wenn der Verbindungsknoten nicht „localhost“ ist:

"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-Eigenschaften

Das SDK enthält einen vorab kuratierten Eigenschaftensatz vom Typ „inventory“, mit dem Sie Bedingungen für die Entscheidung erstellen können, wann Ihr Tool verfügbar sein soll. Das inventory-Array enthält neun verschiedene Eigenschaften:

Eigenschaftenname	Erwarteter Wertetyp
computerManufacturer	Zeichenfolge
operatingSystemSKU	number
operatingSystemVersion	Versionszeichenfolge (z. B. „10.1*“)
productType	number
clusterFqdn	Zeichenfolge
isHyperVRoleInstalled	boolean
isHyperVPowershellInstalled	boolean
isManagementToolsAvailable	boolean
isWmfInstalled	boolean

Die Objekte im inventory-Array müssen der folgenden JSON-Struktur entsprechen:

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

Operatorwerte

Operator	BESCHREIBUNG
gt	Größer als
ge	Größer oder gleich
lt	Kleiner als
le	Kleiner oder gleich
eq	gleich
ne	not equal to (ungleich)
is	überprüft, ob ein Wert TRUE ist
not	überprüft, ob ein Wert FALSE ist
contains	Element ist in einer Zeichenfolge vorhanden
notContains	Element ist nicht in einer Zeichenfolge vorhanden

Datentypen

Folgende Optionen sind für die Eigenschaft „type“ verfügbar:

type	BESCHREIBUNG
version	Versionsnummer (z. B. „10.1*“)
number	numerischer Wert
Zeichenfolge	Zeichenfolgenwert
boolean	true oder false

Werttypen

Die Eigenschaft „value“ akzeptiert die folgenden Typen:

Zeichenfolge
Zahl
boolean

Das folgende Beispiel zeigt einen ordnungsgemäß formatierten Satz von Bedingungen für „inventory“:

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

Skript

Des Weiteren können Sie ein benutzerdefiniertes PowerShell-Skript ausführen, um die Verfügbarkeit und den Status des Knotens zu ermitteln. Alle Skripts müssen ein Objekt mit der folgenden Struktur zurückgeben:

@{
    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'; };
}

Die state-Eigenschaft ist der relevante Wert für die Entscheidung, ob Ihre Erweiterung in der Liste der verfügbaren Tools angezeigt oder ausgeblendet wird. Zulässige Werte sind:

Wert	BESCHREIBUNG
Verfügbar	Die Erweiterung sollte in der Liste der Tools angezeigt werden.
NotSupported	Die Erweiterung sollte nicht in der Liste der Tools angezeigt werden.
NotConfigured	Mit diesem Platzhalterwert für die Zukunft werden Benutzer*innen zu zusätzlichen Konfigurationen aufgefordert, bevor das Tool verfügbar gemacht wird. Derzeit ist dieser Wert das funktionale Äquivalent zu „available“ und führt dazu, dass das Tool angezeigt wird.

Soll ein Tool beispielsweise nur geladen werden, wenn auf dem Remoteserver BitLocker installiert ist, sieht das Skript wie folgt aus:

$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

Eine Einstiegspunktkonfiguration mit der Skriptoption sieht wie folgt aus:

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

Unterstützen mehrerer Anforderungen

Sie können mehrere Anforderungen verwenden, um festzulegen, wann Ihr Tool angezeigt werden soll. Definieren Sie hierzu mehrere Blöcke vom Typ „requirements“.

Wenn Sie Ihr Tool beispielsweise anzeigen möchten, wenn „scenario A“ ODER „scenario B“ zutrifft, definieren Sie zwei Anforderungsblöcke. Ist einer der beiden TRUE (d. h. alle Bedingungen innerhalb eines Anforderungsblocks sind erfüllt), wird das Tool angezeigt.

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

Unterstützen von Bedingungsbereichen

Sie können auch einen Bereich von Bedingungen definieren, indem Sie mehrere Blöcke vom Typ „conditions“ mit derselben Eigenschaft, aber mit unterschiedlichen Operatoren definieren.

Wird dieselbe Eigenschaft mit unterschiedlichen Operatoren definiert, wird das Tool angezeigt, wenn der Wert zwischen den beiden Bedingungen liegt.

Im folgenden Beispiel wird das Tool angezeigt, wenn die Version des Betriebssystems zwischen 6.3.0 und 10.0.0 liegt:

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