Steuern der Sichtbarkeit Ihres Tools in einer Lösung

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. Wenn Ihr Tool beispielsweise nur auf Windows Server 2016 (nicht ältere Versionen) ausgerichtet ist, möchten Sie möglicherweise nicht, dass ein Benutzer, der eine Verbindung mit einem Windows Server 2012 R2-Server herstellt, Ihr Tool überhaupt sehen soll. (Imagine der Benutzeroberfläche: Sie klicken darauf, warten, bis das Tool geladen wurde, und erhalten nur eine Meldung, dass die Features für die 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, wann ein Tool angezeigt werden soll

Es gibt drei verschiedene Optionen, mit denen Sie bestimmen können, ob Ihr Tool angezeigt werden soll 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, der ausgewertet werden kann, um abzuschätzen, ob der Verbindungsknoten localHost ist (derselbe Computer, auf dem Windows Admin Center installiert ist) oder nicht. Indem Sie einen Wert an die -Eigenschaft übergeben, geben Sie an, wann (die Bedingung) das Tool anzeigen soll. Wenn das Tool beispielsweise nur angezeigt werden soll, wenn der Benutzer tatsächlich eine Verbindung mit dem lokalen Host herstellt, richten Sie es wie folgt ein:

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

Wenn Ihr Tool nur angezeigt werden soll, wenn der Knoten, der eine Verbindung herstellt, nicht localhost ist, können Sie alternativ folgendes anzeigen:

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

So sehen die Konfigurationseinstellungen aus, um nur dann ein Tool anzuzeigen, 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 Inventureigenschaften, mit denen Sie Bedingungen erstellen können, um zu bestimmen, wann Ihr Tool verfügbar sein soll. Es gibt neun verschiedene Eigenschaften im Array "inventory":

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 Das Element ist in einer Zeichenfolge vorhanden.
notContains Das Element 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 ein numerischer Wert
Zeichenfolge ein Zeichenfolgenwert
boolean true oder false

Werttypen

Die Value-Eigenschaft akzeptiert diese Typen:

  • Zeichenfolge
  • Zahl
  • boolean

Ein ordnungsgemäß gebildeter Bestandsbedingungssatz 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!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 steuert, ihre Erweiterung in der Toolsliste anzuzeigen oder auszublenden. 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 Toolsliste angezeigt werden.
NotConfigured Dies ist ein Platzhalterwert für zukünftige Arbeiten, der den Benutzer zur zusätzlichen Konfiguration auffordert, bevor das Tool verfügbar gemacht wird. Derzeit führt dieser Wert dazu, dass das Tool angezeigt wird und das funktionale Äquivalent zu "Available" ist.

Wenn ein Tool beispielsweise nur geladen werden soll, 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 mithilfe 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 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 verschiedenen Operatoren definiert ist, wird das Tool angezeigt, solange der Wert zwischen den beiden Bedingungen liegt.

Dieses Tool wird beispielsweise 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"
                }
            }
        }
        ]
    }
    ]
}