ソリューションでツールの表示範囲を制御する

[アーティクル]
03/09/2023
適用対象:

✅ Windows Admin Center, ✅ Windows Admin Center Preview

使用可能なツールの一覧から拡張機能またはツールを除外 (または非表示) したい場合があります。たとえば、ツールのターゲットが Windows Server 2016 のみ (それよりも古いバージョンではない) 場合は、Windows Server 2012 R2 サーバーに接続するユーザーにツールを表示したくない場合があります。 (ユーザーエクスペリエンスを想像してみてください。ユーザーは、ツールをクリックして読み込まれるまで待機したにも関わらず、利用中の接続ではその機能が利用できないという旨のメッセージを見ることになります)。機能をいつ表示する (または非表示にする) かについては、ツールの manifest.json ファイルで定義することができます。

ツールを表示する場合を決定するためのオプション

特定のサーバーまたはクラスター接続に対して、ツールを表示して使用できるようにするかどうかを判断するために、使用できるオプションは 3 種類があります。

localhost
inventory (プロパティの配列)
script

localHost

Conditions オブジェクトの localHost プロパティには、接続ノードが localHost (Windows Admin Center がインストールされているのと同じコンピューター) かどうかを評価できるブール値が含まれています。このプロパティに値を渡して、ツールを表示する場合 (条件) を指定します。たとえば、ユーザーが実際にローカルホストに接続している場合にのみツールを表示する場合は、次のように設定します。

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

または、接続ノードが localhost ではないときのみツールを表示する場合は、次のようにします。

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

接続ノードが 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
        }
        ]
    }
    ]
}

インベントリのプロパティ

SDK には、事前に調整されたインベントリのプロパティのセットが含まれています。このプロパティを使用して、ツールを使用できるかどうかを判断するための条件を作成できます。 'inventory' 配列には 9 つの異なるプロパティがあります。

プロパティ名	期待される値の種類
computerManufacturer	string
operatingSystemSKU	number
operatingSystemVersion	version_string (例: "10.1.*")
productType	number
clusterFqdn	string
isHyperVRoleInstalled	boolean
isHyperVPowershellInstalled	boolean
isManagementToolsAvailable	boolean
isWmfInstalled	boolean

インベントリ配列内のすべてのオブジェクトは、次の json 構造体に準拠している必要があります。

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

演算子の値

演算子	説明
gt	より大きい
ge	以上
lt	次の値未満
le	以下
eq	等しい
ne	等しくない
is	値が true かどうかチェック
not	値が false かどうかチェック
contains	項目が文字列内に存在する
notContains	項目が文字列内に存在しない

データ型

'type' プロパティで使用できるオプションは次のとおりです。

型	説明
version	バージョン番号 (例: 10.1.*)
number	数値
string	文字列値
boolean	true または false

値型

'value' プロパティは、次の型を受け入れます。

文字列
数値
boolean

適切な形式のインベントリ条件セットは次のようになります。

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

スクリプト

最後に、カスタム PowerShell スクリプトを実行して、ノードの可用性と状態を特定できます。すべてのスクリプトは、次の構造のオブジェクトを返す必要があります。

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

State プロパティは、ツールの一覧で拡張機能を表示または非表示にする決定を制御する重要な値です。使用できる値は、次のとおりです。

値	説明
利用可能	拡張機能がツールの一覧に表示されます。
NotSupported	拡張機能がツールの一覧に表示されません。
NotConfigured	これは、将来の作業のためのプレースホルダー値で、ツールを使用できるようにする前にユーザーに追加の構成を求めます。現在は、この値を使うとツールが表示され、'Available' と同等の機能になります。

たとえば、リモートサーバーに BitLocker がインストールされている場合にのみツールを読み込む場合、スクリプトは次のようになります。

$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

スクリプトオプションを使用したエントリポイントの構成は次のようになります。

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

複数の要件セットのサポート

複数の "requirements" ブロックを定義することで、複数の要件セットを使用して、ツールを表示する場合を決定できます。

たとえば、"scenario A" または "scenario B" が true の場合にツールを表示するには、2 つの要件ブロックを定義します。どちらかが true の場合 (つまり、要件ブロック内のすべての条件が満たされている場合)、ツールが表示されます。

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

条件範囲のサポート

また、同じプロパティで異なる演算子を持つ複数の "conditions" ブロックを定義し、条件の範囲を定義できます。

同じプロパティが異なる演算子で定義されている場合、値が 2 つの条件の間である限り、ツールが表示されます。

たとえば、次のツールは、オペレーティングシステムのバージョンが 6.3.0 から 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"
                }
            }
        }
        ]
    }
    ]
}

次の方法で共有