控制工具在解决方案中的可见性Control your tool's visibility in a solution

适用于:Windows Admin Center、Windows Admin Center 预览版Applies 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

您可以使用三个不同的选项来确定是否应显示工具并使其可用于特定服务器或群集连接。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)
  • 脚本script

主机LocalHost

条件对象的 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 包括一组预特选的清单属性,您可以使用这些属性来构建条件,确定何时可以使用您的工具。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. "清单" 数组中有九个不同的属性:There are nine different properties in the 'inventory' array:

属性名称Property Name 预期值类型Expected Value Type
computerManufacturercomputerManufacturer 字符串string
operatingSystemSKUoperatingSystemSKU numbernumber
operatingSystemVersionoperatingSystemVersion version_string (例如: "10.1. *" ) version_string (eg: "10.1.*")
productTypeproductType numbernumber
clusterFqdnclusterFqdn 字符串string
isHyperVRoleInstalledisHyperVRoleInstalled booleanboolean
isHyperVPowershellInstalledisHyperVPowershellInstalled booleanboolean
isManagementToolsAvailableisManagementToolsAvailable 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 检查值是否为 truechecking if a value is true
notnot 检查值是否为 falsechecking 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
版本version 版本号 (例如: 10.1. * ) a version number (eg: 10.1.*)
numbernumber 一个数值a numeric value
字符串string 一个字符串值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'; };
}

"状态" 属性是一个重要值,用于控制在 "工具" 列表中显示或隐藏扩展的决定。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. 当前此值将导致工具显示,并且其功能等效于 "可用"。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.

例如,若要在 "方案 A" 或 "方案 B" 为 true 时显示你的工具,请定义两个要求块;如果任一条件为 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.

如果用不同的运算符定义了同一个属性,则只要这两个条件之间的值,就会显示该工具。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"
                }
            }
        }
        ]
    }
    ]
}