ソリューションでのツールの可視性の制御Control your tool's visibility in a solution

適用先:Windows Admin Center、Windows Admin Center PreviewApplies To: Windows Admin Center, Windows Admin Center Preview

使用可能なツールの一覧から拡張機能またはツールを除外 (または非表示にする) が必要になる場合があります。There might be times when you want to exclude (or hide) your extension or tool from the available tools list. たとえば、ツールが Windows Server 2016 (古いバージョンではない) のみを対象としている場合は、Windows Server 2012 R2 サーバーに接続しているユーザーがまったくツールを表示しないようにする必要があります。For example, if your tool targets only Windows Server 2016 (not older versions), you might not want a user who connects to a Windows Server 2012 R2 server to see your tool at all. (ユーザーエクスペリエンスを想像してください。クリックすると、ツールが読み込まれるまで待機します。その機能が接続に使用できないというメッセージが表示されます)。ツールのファイル manifest.jsで機能を表示 (または非表示) するタイミングを定義できます。(Imagine the user experience - they click on it, wait for the tool to load, only to get a message that its features aren't available for their connection.) You can define when to show (or hide) your feature in the tool's manifest.json file.

ツールを表示するタイミングを決定するためのオプションOptions for deciding when to show a tool

特定のサーバーまたはクラスター接続でツールを表示して使用できるようにするかどうかを決定するために使用できるオプションは3つあります。There are three different options you can use to determine whether your tool should be displayed and available for a specific server or cluster connection.

  • localhostlocalhost
  • インベントリ (プロパティの配列)inventory (an array of properties)
  • scriptscript

LocalHostLocalHost

Condition オブジェクトの localHost プロパティには、接続しているノードが localHost (Windows 管理センターがインストールされている同じコンピューター) であるかどうかを推測するために評価できるブール値が含まれています。The localHost property of the Conditions object contains a boolean value that can be evaluated to infer if the connecting node is localHost (the same computer that Windows Admin Center is installed on) or not. プロパティに値を渡すことによって、いつ (条件) ツールを表示するかを指定します。By passing a value to the property, you indicate when (the condition) to display the tool. たとえば、ユーザーが実際にローカルホストに接続している場合にのみツールを表示するには、次のように設定します。For example if you only want the tool to display if the user is in fact connecting to the local host, set it up like this:

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

また、接続しているノードが localhost でない場合にのみツールを表示するには、次のようにします。Alternatively, if you only want your tool to display when the connecting node is not localhost:

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

接続しているノードが localhost でない場合にのみツールを表示するように構成設定が表示されるのは次のようになります。Here's what the configuration settings look like to only show a tool when the connecting node is not 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
        }
        ]
    }
    ]
}

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

SDK には、curated のインベントリプロパティのセットが含まれています。これらのプロパティを使用して、ツールをいつ使用できるようにするかを決定するための条件を作成できます。The SDK includes a pre-curated set of inventory properties that you can use to build conditions to determine when your tool should be available or not. ' Inventory ' 配列には、次の9つの異なるプロパティがあります。There are nine different properties in the 'inventory' array:

プロパティ名Property Name 予期される値の型Expected Value Type
コンピューターの製造元computerManufacturer stringstring
operatingSystemSKUoperatingSystemSKU numbernumber
operatingSystemVersionoperatingSystemVersion version_string (例: "10.1. *")version_string (eg: "10.1.*")
productTypeproductType numbernumber
clusterFqdnclusterFqdn stringstring
isHyperVRoleInstalledisHyperVRoleInstalled booleanboolean
isHyperVPowershellInstalledisHyperVPowershellInstalled booleanboolean
Ismanagementツールを使用できますisManagementToolsAvailable booleanboolean
isWmfInstalledisWmfInstalled booleanboolean

インベントリ配列内のすべてのオブジェクトは、次の json 構造に準拠している必要があります。Every object in the inventory array must conform to the following json structure:

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

演算子の値Operator values

演算子Operator 説明Description
gtgt より大きいgreater than
gege 以上greater than or equal to
ltlt 次の値未満less than
lele 以下less than or equal to
eqeq 等しいequal to
nene 等しくないnot equal to
isis 値が true であるかどうかを確認していますchecking if a value is true
notnot 値が false かどうかを確認していますchecking if a value is false
containscontains 項目が文字列内に存在しますitem exists in a string
notContainsnotContains 項目が文字列内に存在しませんitem does not exist in a string

データ型Data types

' Type ' プロパティで使用可能なオプション:Available options for the 'type' property:

種類Type 説明Description
versionversion バージョン番号 (例: 10.1. *)a version number (eg: 10.1.*)
numbernumber 数値a numeric value
stringstring 文字列値a string value
booleanboolean true または falsetrue or false

値型Value types

' Value ' プロパティは、次の型を受け取ります。The 'value' property accepts these types:

  • 文字列string
  • 数値number
  • booleanboolean

正しい形式のインベントリ条件セットは次のようになります。A properly-formed inventory condition set looks like this:

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

スクリプトScript

最後に、カスタム PowerShell スクリプトを実行して、ノードの可用性と状態を識別できます。Finally, you can run a custom PowerShell script to identify the availability and state of the node. すべてのスクリプトは、次の構造を持つオブジェクトを返す必要があります。All scripts must return an object with the following structure:

@{
    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 プロパティは、[ツール] ボックスの一覧で拡張機能を表示または非表示にする決定を制御する重要な値です。The State property is the important value that will control the decision to show or hide your extension in the tools list. 使用できる値は、次のとおりです。The allowed values are:

Value 説明Description
利用可能Available 拡張機能が [ツール] ボックスの一覧に表示されます。The extension should be displayed in the tools list.
NotSupportedNotSupported 拡張機能は、[ツール] ボックスの一覧に表示されません。The extension should not be displayed in the tools list.
NotConfiguredNotConfigured これは、ツールが使用可能になる前にユーザーに追加の構成を求めるプロンプトを表示する、今後の作業のためのプレースホルダー値です。This is a placeholder value for future work that will prompt the user for additional configuration before the tool is made available. 現在この値を指定すると、ツールが表示されます。これは、' Available ' と同等の機能です。Currently this value will result in the tool being displayed and is the functional equivalent to 'Available'.

たとえば、リモートサーバーに BitLocker がインストールされている場合にのみツールを読み込むようにするには、スクリプトは次のようになります。For example, if we want a tool to load only if the remote server has BitLocker installed, the script looks like this:

$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

スクリプトオプションを使用したエントリポイントの構成は次のようになります。An entry point configuration using the script option looks like this:

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

複数の要件セットのサポートSupporting multiple requirement sets

複数の要件セットを使用して、複数の "要件" ブロックを定義することで、どのようなときにツールを表示するかを決定できます。You can use more than one set of requirements to determine when to display your tool by defining multiple "requirements" blocks.

たとえば、"scenario A" または "scenario B" が true の場合にツールを表示するには、2つの要件ブロックを定義します。いずれかが true の場合 (つまり、要件ブロック内のすべての条件が満たされる場合)、ツールが表示されます。For example, to display your tool if "scenario A" OR "scenario B" is true, define two requirements blocks; if either is true (that is, all conditions within a requirements block are met), the tool is displayed.

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

条件範囲のサポートSupporting condition ranges

また、同じプロパティを持つ複数の "条件" ブロックを定義して、さまざまな演算子で条件の範囲を定義することもできます。You can also define a range of conditions by defining multiple "conditions" blocks with the same property, but with different operators.

同じプロパティが異なる演算子で定義されている場合、値が2つの条件の間にある限り、ツールが表示されます。When the same property is defined with different operators, the tool is displayed as long as the value is between the two conditions.

たとえば、オペレーティングシステムが6.3.0 と10.0.0 の間のバージョンである限り、このツールが表示されます。For example, this tool is displayed as long as the operating system is a version between 6.3.0 and 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"
                }
            }
        }
        ]
    }
    ]
}