在解決方案中控制工具的可見度

文章
02/21/2024

適用於：Windows Admin Center、Windows Admin Center 預覽版

有時候您可能會想要從可用的工具清單中排除 (或隱藏) 延伸模組或工具。例如，如果您的工具僅以 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 包含一組預先策劃的清查屬性，可讓您用來建置條件來判斷工具何時應可供使用。「清查」陣列中有九個不同的屬性：

屬性名稱	預期的值類型
computerManufacturer	string
operatingSystemSKU	數值
operatingSystemVersion	版本字串 (例如: "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	不等於
is	檢查值是否為 true
not	檢查值是否為 false
contains	專案存在於字串中
notContains	專案不存在於字串中

資料類型

'type' 屬性的可用選項：

類型	描述
version	版本號碼 (例如: 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"
            }
            }
        }
        ]
    }
    ]
}

指令碼

最後，您可以執行自訂 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 屬性是控制在工具清單中顯示或隱藏延伸模組之決策的重要值。允許的值包括：

值	Description
可使用	延伸模組應該會顯示在工具清單中。
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"
                }
            }
        }
        ]
    }
    ]
}

分享方式：