Controlar a visibilidade da ferramenta em uma solução

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':

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

Tipos de dados

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

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:

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