Compartilhar via

Controlar a visibilidade da ferramenta em uma solução

  • Artigo
  • Aplica-se a:
    ✅ Windows Admin Center, ✅ Windows Admin Center Preview

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