在解决方案中控制工具的可见性

项目
11/02/2024
适用于:

✅ Windows Admin Center, ✅ Windows Admin Center Preview

有时，你可能希望从可用工具列表中排除（或隐藏）你的扩展或工具。例如，如果你的工具仅面向 Windows Server 2016（而不是更低版本），你可能完全不想连接到 Windows Server 2012 R2 服务器的用户看到你的工具。（想象一下用户体验 - 用户单击它，等待工具加载，但只收到一条消息，它显示他们连接后无法使用工具的功能。）可定义何时在工具的 manifest.json 文件中显示（或隐藏）你的功能。

用于决定何时显示工具的选项

有三个不同的选项可用来确定是否应显示你的工具，以及你的工具是否可用于特定服务器或群集连接。

localhost
清单（属性数组）
脚本

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 包含一组预先精选的清单属性，可使用这些属性生成条件来确定工具何时可用。 “清单”数组中有 9 个不同的属性：

属性名称	预期的值类型
computerManufacturer	string
operatingSystemSKU	数字
operatingSystemVersion	version_string（例如“10.1.*”）
productType	编号
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	不等于
是	检查值是否为 true
not	检查值是否为 false
contains	项存在于字符串中
notContains	项不存在于字符串中

数据类型

“type”属性的可用选项：

类型	说明
版本	版本号（例如 10.1.*）
编号	数值
string	字符串值
boolean	true 或 false

值类型

“value”属性接受以下类型：

string
数字
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"
            }
            }
        }
        ]
    }
    ]
}

Script

最后，可以运行自定义 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	这是可稍后填充的占位符值，它将在工具可用之前提示用户进行其他配置。目前，此值将导致显示工具，其功能与“可用”设置相当。

例如，如果只想在远程服务器安装了 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"
        }
        ]
    }
    ]
}

支持多个要求集

通过定义多个“要求”块，可以使用多个要求集来确定何时显示工具。

例如，若要在“方案 A”或“方案 B”为 true 时显示工具，请定义两个要求块；两者之一为 true 时（即满足要求块中的所有条件），会显示工具。

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

支持条件范围

还可以通过定义多个具有相同属性但具有不同运算符的“条件”块来定义一系列条件。

使用不同的运算符定义相同属性时，只要值介于两个条件之间，就会显示工具。

例如，只要操作系统的版本介于 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"
                }
            }
        }
        ]
    }
    ]
}

通过