Steuern der Sichtbarkeit Ihres Tools in einer Lösung

  • Artikel
  • 5 Minuten Lesedauer

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

Möglicherweise möchten Sie Ihre Erweiterung oder Ihr Tool aus der Liste der verfügbaren Tools ausschließen (oder ausblenden). Wenn Ihr Tool beispielsweise nur auf Windows Server 2016 (keine älteren Versionen) zielt, möchten Sie möglicherweise nicht, dass ein Benutzer, der eine Verbindung mit einem Windows Server 2012 R2-Server herstellt, Ihr Tool überhaupt sehen kann. (Imagine die Benutzeroberfläche: Sie klicken darauf, warten, bis das Tool geladen wird, nur um eine Meldung zu erhalten, 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 ausblendet) werden soll.

Optionen für die Entscheidung, wann ein Tool angezeigt werden soll

Es gibt drei verschiedene Optionen, mit derenHilfe Sie bestimmen können, ob Ihr Tool für eine bestimmte Server- oder Clusterverbindung angezeigt und verfügbar sein soll.

  • Localhost
  • inventory (ein Array von Eigenschaften)
  • script

Localhost

Die localHost-Eigenschaft des Conditions-Objekts enthält einen booleschen Wert, der ausgewertet werden kann, um daraus zu schließen, ob der Verbindungsknoten localHost ist (derselbe Computer, auf dem Windows Admin Center installiert ist) oder nicht. Durch Übergeben eines Werts an die -Eigenschaft geben Sie an, wann (die Bedingung) das Tool angezeigt werden soll. Wenn das Tool beispielsweise nur angezeigt werden soll, wenn der Benutzer tatsächlich eine Verbindung mit dem lokalen Host herstellen soll, richten Sie es wie hier gezeigt ein:

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

Wenn Sie möchten, dass Ihr Tool nur angezeigt wird, wenn der Verbindungsknoten nicht localhost ist, können Sie dies auch:

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

Die Konfigurationseinstellungen sehen so aus, dass nur dann ein Tool angezeigt wird, 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
        }
        ]
    }
    ]
}

Bestandseigenschaften

Das SDK enthält einen vorab zusammengestellten Satz von Bestandseigenschaften, mit denen Sie Bedingungen erstellen können, um zu bestimmen, wann Ihr Tool verfügbar sein soll. Das Array "inventory" enthält neun verschiedene Eigenschaften:

Eigenschaftenname Erwarteter Werttyp
computerManufacturer Zeichenfolge
operatingSystemSKU number
operatingSystemVersion version_string (z.B. "10.1.*")
productType number
clusterFqdn Zeichenfolge
isHyperVRoleInstalled boolean
isHyperVPowershellInstalled boolean
isManagementToolsAvailable boolean
isWmfInstalled boolean

Jedes Objekt im Inventurarray muss 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üfen, ob ein Wert true ist
not Überprüfen, ob ein Wert FALSE ist
contains Element in einer Zeichenfolge vorhanden
notContains Item ist in einer Zeichenfolge nicht vorhanden

Datentypen

Verfügbare Optionen für die Type-Eigenschaft:

type BESCHREIBUNG
version eine Versionsnummer (z.B. 10.1.*)
number einen numerischen Wert
Zeichenfolge ein Zeichenfolgenwert
boolean true oder false

Werttypen

Die Value-Eigenschaft akzeptiert die folgenden Typen:

  • Zeichenfolge
  • Zahl
  • boolean

Ein ordnungsgemäß gebildeter Inventurbedingungssatz sieht wie hier 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!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

Schließlich können Sie ein benutzerdefiniertes PowerShell-Skript ausführen, um die Verfügbarkeit und den Status des Knotens zu identifizieren. 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 wichtige Wert, der die Entscheidung zum Ein- oder Ausblenden Ihrer Erweiterung in der Toolsliste kontrolliert. 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 Dies ist ein Platzhalterwert für zukünftige Arbeit, der den Benutzer zur Eingabe zusätzlicher Konfigurationen auffordern wird, bevor das Tool verfügbar gemacht wird. Derzeit führt dieser Wert dazu, dass das Tool angezeigt wird, und ist das funktionale Äquivalent zu "Verfügbar".

Wenn beispielsweise ein Tool nur geladen werden soll, wenn BitLocker auf dem Remoteserver installiert ist, sieht das Skript wie im folgenden Beispiel 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 mithilfe der Skriptoption sieht wie die folgende 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 Anforderungssätze

Sie können mehrere Anforderungen verwenden, um zu bestimmen, wann Ihr Tool angezeigt werden soll, indem Sie mehrere "Anforderungsblöcke" definieren.

Definieren Sie beispielsweise zwei Anforderungsblöcke, um Ihr Tool anzuzeigen, wenn "Szenario A" ODER "Szenario B" zutrifft. Wenn eines der Beiden true ist (d. h., alle Bedingungen innerhalb eines Anforderungsblocks erfüllt sind), 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ützende Bedingungsbereiche

Sie können auch einen Bereich von Bedingungen definieren, indem Sie mehrere "Bedingungen"-Blöcke mit derselben Eigenschaft, aber mit unterschiedlichen Operatoren definieren.

Wenn dieselbe Eigenschaft mit unterschiedlichen Operatoren definiert ist, wird das Tool angezeigt, solange der Wert zwischen den beiden Bedingungen liegt.

Beispielsweise wird dieses Tool angezeigt, solange das Betriebssystem eine Version zwischen 6.3.0 und 10.0.0 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!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"
                }
            }
        }
        ]
    }
    ]
}