Controlar a visibilidade da ferramenta em uma solução

Artigo
04/12/2023

Aplica-se a: Windows Admin Center, Versão prévia do Windows Admin Center

Pode haver ocasiões em que você deseja excluir (ou ocultar) sua extensão ou ferramenta da lista de ferramentas disponíveis. Por exemplo, se sua ferramenta for direcionada apenas para o Windows Server 2016 (não versões mais antigas), talvez você não queira que um usuário que se conecte a um servidor Windows Server 2012 R2 para ver sua ferramenta. (Imagine a experiência do usuário – ele clica nela, aguarda a ferramenta carregar, apenas para obter uma mensagem de que seus recursos não estão disponíveis para sua conexão.) Você pode definir quando mostrar (ou ocultar) seu recurso no arquivo manifest.json da ferramenta.

Opções para decidir quando mostrar uma ferramenta

Há três opções diferentes que você pode usar para determinar se sua ferramenta deve ser exibida e estar disponível para uma conexão específica de servidor ou cluster.

localhost
estoque (uma matriz de propriedades)
Script

LocalHost

A propriedade localHost do objeto Conditions contém um valor booliano que pode ser avaliado para inferir se o nó de conexão é localHost (o mesmo computador no qual o Windows Admin Center está instalado) ou não. Ao passar um valor para a propriedade, você indica quando (a condição) exibir a ferramenta. Por exemplo, se você quiser que a ferramenta seja exibida somente se o usuário estiver de fato se conectando ao host local, configure-a da seguinte maneira:

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

Como alternativa, se você quiser que sua ferramenta seja exibida apenas quando o nó de conexão não for localhost:

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

Esta é a aparência das definições de configuração para mostrar apenas uma ferramenta quando o nó de conexão não for 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
        }
        ]
    }
    ]
}

Propriedades de estoque

O SDK inclui um conjunto pré-coletado de propriedades de estoque que você pode usar para criar condições para determinar quando sua ferramenta deve estar disponível ou não. Há nove propriedades diferentes na matriz de 'estoque':

Nome da propriedade	Tipo de valor esperado
computerManufacturer	string
operatingSystemSKU	número
operatingSystemVersion	version_string (por exemplo: "10.1.*")
productType	número
clusterFqdn	string
isHyperVRoleInstalled	booleano
isHyperVPowershellInstalled	booleano
isManagementToolsAvailable	booleano
isWmfInstalled	booleano

Cada objeto na matriz de estoque deve estar em conformidade com a seguinte estrutura json:

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

Valores do operador

Operador	Descrição
gt	maior que
ge	maior que ou igual a
lt	menor que
le	menor que ou igual a
eq	igual a
ne	diferente de
está	verificando se um valor é true
não	verificando se um valor é true
contém	o item existe em uma cadeia de caracteres
notContains	o item não existe em uma cadeia de caracteres

Tipos de dados

Opções disponíveis para a propriedade 'type':

Type	Descrição
version	um número de versão (por exemplo: 10.1.*)
número	um valor numérico
string	um valor de cadeia de caracteres
booleano	true ou false

Tipos de valor

A propriedade 'value' aceita estes tipos:

cadeia de caracteres
número
booleano

Um conjunto de condições de estoque corretamente formado tem esta aparência:

"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

Por fim, você pode executar um script personalizado do PowerShell para identificar a disponibilidade e o estado do nó. Todos os scripts devem retornar um objeto com a seguinte estrutura:

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

A propriedade State é o valor importante que vai controlar a decisão de mostrar ou ocultar sua extensão na lista de ferramentas. Os valores permitidos são:

Valor	Descrição
Disponível	A extensão deve ser exibida na lista de ferramentas.
NotSupported	A extensão não deve ser exibida na lista de ferramentas.
NotConfigured	Esse é um valor de espaço reservado para trabalho futuro que solicitará ao usuário uma configuração adicional antes que a ferramenta fique disponível. Atualmente, esse valor resultará na exibição da ferramenta e é o equivalente funcional a 'Disponível'.

Por exemplo, se quisermos que uma ferramenta seja carregada somente se o servidor remoto tiver o BitLocker instalado, o script terá esta aparência:

$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

Uma configuração de ponto de entrada usando a opção de script tem esta aparência:

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

Suporte a vários conjuntos de requisitos

Você pode usar mais de um conjunto de requisitos para determinar quando exibir sua ferramenta definindo vários blocos de "requisitos".

Por exemplo, para exibir sua ferramenta se "cenário A" OU "cenário B" for verdadeiro, defina dois blocos de requisitos; se qualquer um for verdadeiro (ou seja, todas as condições dentro de um bloco de requisitos serão atendidas), a ferramenta será exibida.

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

Suporte a intervalos de condições

Você também pode definir um intervalo de condições definindo vários blocos de "condições" com a mesma propriedade, mas com operadores diferentes.

Quando a mesma propriedade é definida com operadores diferentes, a ferramenta é exibida desde que o valor esteja entre as duas condições.

Por exemplo, essa ferramenta é exibida desde que o sistema operacional seja uma versão entre 6.3.0 e 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"
                }
            }
        }
        ]
    }
    ]
}

Compartilhar via