Control de la visibilidad de la herramienta en una solución

Artículo
03/09/2023
Se aplica a:

✅ Windows Admin Center, ✅ Windows Admin Center Preview

A veces, podría interesarle excluir (u ocultar) la extensión o herramienta de la lista de herramientas disponibles. Por ejemplo, si la herramienta solo tiene como destino Windows Server 2016 (no versiones anteriores), es posible que no quiera que un usuario que se conecta a un servidor de Windows Server 2012 R2 vea la herramienta. (Imagine la experiencia del usuario: hace clic en la herramienta, espera a que se cargue y obtiene un mensaje que le indica que las características no están disponibles para su conexión). Puede definir cuándo se debe mostrar (u ocultar) la característica en el archivo manifest.json de la herramienta.

Opciones para decidir cuándo mostrar una herramienta

Puede usar tres opciones diferentes para determinar si la herramienta debe mostrarse y estar disponible para una conexión de clúster o servidor específica.

localhost
inventario (una matriz de propiedades)
script

localhost

La propiedad localhost del objeto Conditions contiene un valor booleano que se puede evaluar para deducir si el nodo de conexión es localhost (el mismo equipo en el que está instalado Windows Admin Center) o no. Al pasar un valor a la propiedad, está indicando cuándo (esto es, la condición) se muestra la herramienta. Por ejemplo, si solo quiere que la herramienta se muestre si el usuario se está conectando al host local, establézcalo de la manera siguiente:

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

Si solo quiere que la herramienta se muestre cuando el nodo de conexión no es localhost:

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

Este es el aspecto que tienen los valores de configuración al mostrar solo una herramienta cuando el nodo de conexión no es 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
        }
        ]
    }
    ]
}

Propiedades de inventario

El SDK incluye un conjunto previamente mantenido de propiedades de inventario que puede usar para crear condiciones que le permitan determinar cuándo debe estar disponible o no la herramienta. Hay nueve propiedades diferentes en la matriz de inventario:

Nombre de propiedad	Tipo de valor esperado
computerManufacturer	string
operatingSystemSKU	number
operatingSystemVersion	version_string (por ejemplo, "10.1.*")
productType	number
clusterFqdn	string
isHyperVRoleInstalled	boolean
isHyperVPowershellInstalled	boolean
isManagementToolsAvailable	boolean
isWmfInstalled	boolean

Cada objeto de la matriz de inventario debe ajustarse a la siguiente estructura json:

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

Valores del operador

Operador	Descripción
gt	mayor que
ge	Mayor o igual que
lt	menor que
le	Menor o igual que
eq	igual a
ne	not equal to
is	comprobación de si un valor es true
not	comprobación de si un valor es false
contains	el elemento existe en una cadena
notContains	el elemento no existe en una cadena

Tipos de datos

Opciones disponibles para la propiedad "type":

Tipo	Descripción
version	número de versión (por ejemplo, "10.1.*")
number	valor numérico
string	valor de cadena
boolean	true o false

Tipos de valor

La propiedad "value" acepta estos tipos:

cadena
número
boolean

Un conjunto de condiciones de inventario formado correctamente tiene este aspecto:

"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 último, puede ejecutar un script de PowerShell personalizado para identificar la disponibilidad y el estado del nodo. Todos los scripts deben devolver un objeto con la estructura siguiente:

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

La propiedad State es un valor importante que controlará la decisión de mostrar u ocultar la extensión en la lista de herramientas. Los valores permitidos son:

Valor	Descripción
Disponible	La extensión debe mostrarse en la lista de herramientas.
NotSupported	La extensión no debe mostrarse en la lista de herramientas.
NoConfigurado	Se trata de un valor de marcador de posición para el trabajo futuro que solicitará al usuario una configuración adicional antes de que la herramienta esté disponible. Actualmente, este valor hará que se muestre la herramienta y es el equivalente funcional a "Disponible".

Por ejemplo, si queremos que una herramienta se cargue solo si el servidor remoto tiene BitLocker instalado, el script tiene este aspecto:

$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

Una configuración de punto de entrada con la opción script tiene este aspecto:

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

Compatibilidad con varios conjuntos de requisitos

Puede usar más de un conjunto de requisitos para determinar cuándo se mostrará la herramienta. Para ello, defina varios bloques de tipo "requirements".

Por ejemplo, para mostrar la herramienta si "scenario A" o "scenario B" son true, defina dos bloques de requisitos; si se cumple alguno de ellos (es decir, si se cumplen todas las condiciones de un bloque de requisitos), la herramienta se mostrará.

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

Compatibilidad con intervalos de condiciones

También puede definir un intervalo de condiciones. Para ello, defina varios bloques de tipo "conditions" con la misma propiedad, pero con operadores diferentes.

Cuando la misma propiedad se define con operadores diferentes, la herramienta se muestra siempre que el valor se encuentre entre las dos condiciones.

Por ejemplo, esta herramienta se muestra siempre que el sistema operativo sea una versión entre 6.3.0 y 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"
                }
            }
        }
        ]
    }
    ]
}

Compartir a través de