Steuern der Sichtbarkeit Ihres Tools in einer Lösung

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:

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

Datentypen

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

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:

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