Creación de un proveedor de conexión para una extensión de solución

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

✅ Windows Admin Center, ✅ Windows Admin Center Preview

Los proveedores de conexión desempeñan un papel importante en la forma en que Windows Admin Center define objetos o destinos conectables y se comunica con ellos. Principalmente, un proveedor de conexión realiza acciones mientras se realiza una conexión, como asegurarse de que el destino está en línea y disponible, y también garantiza que el usuario que se conecta tiene permiso para acceder al destino.

De forma predeterminada, Windows Admin Center se incluye con los siguientes proveedores de conexión:

Server
Cliente Windows
Clúster de conmutación por error
Clúster de HCI

Para crear su propio proveedor de conexión personalizado, siga estos pasos:

Agregue los detalles del proveedor de conexión a manifest.json.
Defina el proveedor de estado de la conexión.
Implemente el proveedor de conexión en la capa de aplicación.

Adición de detalles del proveedor de conexión a manifest.json

Ahora veremos lo que necesita saber para definir un proveedor de conexión en el archivo manifest.json del proyecto.

Creación de una entrada en manifest.json

El archivo manifest.json se encuentra en la carpeta \src y contiene, entre otras cosas, definiciones de puntos de entrada en el proyecto. Los tipos de puntos de entrada incluyen herramientas, soluciones y proveedores de conexión. Definiremos un proveedor de conexión.

A continuación se muestra un ejemplo de una entrada del proveedor de conexión en manifest.json:

    {
      "entryPointType": "connectionProvider",
      "name": "addServer",
      "path": "/add",
      "displayName": "resources:strings:addServer_displayName",
      "icon": "sme-icon:icon-win-server",
      "description": "resources:strings:description",
      "connectionType": "msft.sme.connection-type.server",
      "connectionTypeName": "resources:strings:addServer_connectionTypeName",
      "connectionTypeUrlName": "server",
      "connectionTypeDefaultSolution": "msft.sme.server-manager!servers",
      "connectionTypeDefaultTool": "msft.sme.server-manager!overview",
      "connectionStatusProvider": {
        "powerShell": {
          "script": "## Get-My-Status ##\nfunction Get-Status()\n{\n# A function like this would be where logic would exist to identify if a node is connectable.\n$status = @{label = $null; type = 0; details = $null; }\n$caption = \"MyConstCaption\"\n$productType = \"MyProductType\"\n# A result object needs to conform to the following object structure to be interpreted properly by the Windows Admin Center shell.\n$result = @{ status = $status; caption = $caption; productType = $productType; version = $version }\n# DO FANCY LOGIC #\n# Once the logic is complete, the following fields need to be populated:\n$status.label = \"Display Thing\"\n$status.type = 0 # This value needs to conform to the LiveConnectionStatusType enum. >= 3 represents a failure.\n$status.details = \"success stuff\"\nreturn $result}\nGet-Status"
        },
        "displayValueMap": {
          "wmfMissing-label": "resources:strings:addServer_status_wmfMissing_label",
          "wmfMissing-details": "resources:strings:addServer_status_wmfMissing_details",
          "unsupported-label": "resources:strings:addServer_status_unsupported_label",
          "unsupported-details": "resources:strings:addServer_status_unsupported_details"
        }
      }
    },

Un punto de entrada de tipo "connnectionProvider" indica al shell de Windows Admin Center que el elemento configurado es un proveedor que una solución usará para validar un estado de conexión. Los puntos de entrada del proveedor de conexión contienen una serie de propiedades importantes, que se definen a continuación:

Propiedad	Descripción
entryPointType	Es una propiedad necesaria. Hay tres valores válidos: "tool", "solution" y "connectionProvider".
name	Identifica el proveedor de conexión dentro del ámbito de una solución. Este valor debe ser único dentro de una instancia completa de Windows Admin Center (no solo una solución).
path	Representa la ruta de acceso de la dirección URL de la interfaz de usuario "Agregar conexión", si la solución la configura. Este valor debe asignarse a una ruta configurada en el archivo app-routing.module.ts. Cuando el punto de entrada de la solución está configurado para usar las conexiones rootNavigationBehavior, esta ruta cargará el módulo que usa el shell para mostrar la interfaz de usuario de "Agregar conexión". Hay más información disponible en la sección sobre rootNavigationBehavior.
DisplayName	El valor especificado aquí se muestra en el lado derecho del shell, debajo de la barra de Windows Admin Center negra cuando un usuario carga la página de conexiones de una solución.
icon	Representa el icono usado en el menú desplegable "Soluciones" para representar la solución.
description	Escriba una breve descripción del punto de entrada.
connectionType	Representa el tipo de conexión que cargará el proveedor. El valor especificado aquí también se usará en el punto de entrada de la solución para especificar que la solución puede cargar esas conexiones. El valor especificado aquí también se usará en los puntos de entrada de la herramienta para indicar que la herramienta es compatible con este tipo. Este valor especificado aquí también se usará en el objeto de conexión que se envía a la llamada RPC en la ventana "Agregar", en el paso de implementación de la capa de aplicación.
connectionTypeName	Se usa en la tabla de conexiones para representar una conexión que usa el proveedor de conexión. Se espera que sea el nombre plural del tipo.
connectionTypeUrlName	Se usa para crear la dirección URL que representa la solución cargada, después de que Windows Admin Center se ha conectado a una instancia. Esta entrada se usa después de las conexiones y antes del destino. En este ejemplo, "connectionexample" es donde este valor aparece en la dirección URL `http://localhost:6516/solutionexample/connections/connectionexample/con-fake1.corp.contoso.com`.
connectionTypeDefaultSolution	Representa el componente predeterminado que el proveedor de conexión debe cargar. Este valor es una combinación de: [a] Nombre del paquete de extensión definido en la parte superior del manifiesto. [b] Signo de exclamación (!). [c] Nombre del punto de entrada de la solución. Para un proyecto con el nombre "msft.sme.mySample-extension" y un punto de entrada de solución con el nombre "example", este valor sería "msft.sme.solutionExample-extension!example".
connectionTypeDefaultTool	Representa la herramienta predeterminada que se debe cargar en una conexión correcta. Este valor de propiedad se compone de dos partes, de forma similar a connectionTypeDefaultSolution. Este valor es una combinación de: [a] Nombre del paquete de extensión definido en la parte superior del manifiesto. [b] Signo de exclamación (!). [c] Nombre del punto de entrada de la herramienta que se debe cargar inicialmente. Para un proyecto con el nombre "msft.sme.solutionExample-extension" y un punto de entrada de solución con el nombre "example", este valor sería "msft.sme.solutionExample-extension!example".
connectionStatusProvider	Consulte la sección "Definición del proveedor de estado de la conexión".

Defina el proveedor de estado de la conexión.

El proveedor de estado de la conexión es el mecanismo por el que se valida que un destino está en línea y disponible, lo que también garantiza que el usuario que se conecta tenga permiso para acceder al destino. Actualmente hay dos tipos de proveedores de estado de la conexión: PowerShell y RelativeGatewayUrl.

Proveedor de estado de la conexión de PowerShell: determina si un destino está en línea y es accesible con un script de PowerShell. El resultado debe devolverse en un objeto con una sola propiedad "status", definida a continuación.
Proveedor de estado de la conexión de RelativeGatewayUrl: determina si un destino está en línea y es accesible con una llamada de REST. El resultado debe devolverse en un objeto con una sola propiedad "status", definida a continuación.

Definición del estado

Los proveedores de estado de la conexión son necesarios para devolver un objeto con una sola propiedad status que se ajuste al siguiente formato:

{
    status: {
        label: string;
        type: int;
        details: string;
    }
}

Propiedades de estado:

Etiqueta: etiqueta que describe el tipo de valor devuelto de estado. Tenga en cuenta que los valores de la etiqueta se pueden asignar en tiempo de ejecución. Consulte la entrada siguiente para ver los valores de asignación en tiempo de ejecución.
Tipo: tipo de valor devuelto de estado. El tipo tiene los siguientes valores de enumeración. Para cualquier valor 2 o superior, la plataforma no se dirigirá al objeto conectado y se mostrará un error en la interfaz de usuario.

Tipos:

Valor Descripción

0 En línea

1 Advertencia

2 No autorizado

3 Error

4 Grave

5 Unknown
Detalles: detalles adicionales que describen el tipo de valor devuelto de estado.

Valor	Descripción
0	En línea
1	Advertencia
2	No autorizado
3	Error
4	Grave
5	Unknown

Script del proveedor de estado de la conexión de PowerShell

El script de PowerShell del proveedor de estado de la conexión determina si un destino está en línea y es accesible con un script de PowerShell. El resultado debe devolverse en un objeto con una sola propiedad "status". A continuación se muestra un script de ejemplo.

Ejemplo de script de PowerShell:

## Get-My-Status ##

function Get-Status()
{
    # A function like this would be where logic would exist to identify if a node is connectable.
    $status = @{label = $null; type = 0; details = $null; }
    $caption = "MyConstCaption"
    $productType = "MyProductType"

    # A result object needs to conform to the following object structure to be interperated properly by the Windows Admin Center shell.
    $result = @{ status = $status; caption = $caption; productType = $productType; version = $version }

    # DO FANCY LOGIC #

    # Once the logic is complete, the following fields need to be populated:
    $status.label = "Display Thing"
    $status.type = 0 # This value needs to conform to the LiveConnectionStatusType enum. >= 3 represents a failure.
    $status.details = "success stuff"

    return $result
}

Get-Status

Definición del método RelativeGatewayUrl del proveedor de estado de la conexión

El método RelativeGatewayUrl del proveedor de estado de la conexión llama a una API REST para determinar si un destino está en línea y es accesible. El resultado debe devolverse en un objeto con una sola propiedad "status". A continuación se muestra un ejemplo de entrada del proveedor de conexión en el archivo manifest.json del método RelativeGatewayUrl.

    {
      "entryPointType": "connectionProvider",
      "name": "addServer",
      "path": "/add/server",
      "displayName": "resources:strings:addServer_displayName",
      "icon": "sme-icon:icon-win-server",
      "description": "resources:strings:description",
      "connectionType": "msft.sme.connection-type.server",
      "connectionTypeName": "resources:strings:addServer_connectionTypeName",
      "connectionTypeUrlName": "server",
      "connectionTypeDefaultSolution": "msft.sme.server-manager!servers",
      "connectionTypeDefaultTool": "msft.sme.server-manager!overview",
      "connectionStatusProvider": {
        "relativeGatewayUrl": "<URL here post /api>",
        "displayValueMap": {
          "wmfMissing-label": "resources:strings:addServer_status_wmfMissing_label",
          "wmfMissing-details": "resources:strings:addServer_status_wmfMissing_details",
          "unsupported-label": "resources:strings:addServer_status_unsupported_label",
          "unsupported-details": "resources:strings:addServer_status_unsupported_details"
        }
      }
    },

Notas sobre el uso de RelativeGatewayUrl:

"RelativeGatewayUrl" especifica dónde obtener el estado de conexión de una dirección URL de puerta de enlace. Este URI es relativo de /api. Si $connectionName se encuentra en la dirección URL, se reemplazará por el nombre de la conexión.
Todas las propiedades de RelativeGatewayUrl deben ejecutarse en la puerta de enlace de host, lo que se puede lograr mediante la creación de una extensión de puerta de enlace.

Asignación de valores en tiempo de ejecución

Los valores de etiqueta y detalles del objeto devuelto de estado se pueden formatear en tiempo de ajuste mediante la inclusión de claves y valores en la propiedad "defaultValueMap" del proveedor.

Por ejemplo, si agrega el valor siguiente, siempre que "defaultConnection_test" aparezca como valor para la etiqueta o los detalles, Windows Admin Center reemplazará automáticamente la clave por el valor de cadena de recurso configurado.

    "defaultConnection_test": "resources:strings:addServer_status_defaultConnection_label"

Implementación del proveedor de conexión en la capa de aplicación

Ahora vamos a implementar el proveedor de conexión en la capa de aplicación mediante la creación de una clase TypeScript que implemente OnInit. La clase tiene las siguientes funciones:

Función	Descripción
constructor(private appContextService: AppContextService, private route: ActivatedRoute)
public ngOnInit()
public onSubmit()	Contiene lógica para actualizar el shell cuando se realiza un intento de agregar una conexión.
public onCancel()	Contiene lógica para actualizar el shell cuando se cancela un intento de agregar una conexión.

Definición de onSubmit

onSubmit emite una devolución de llamada RPC al contexto de la aplicación para notificar al shell una acción "Agregar conexión". La llamada básica usa "updateData" de la siguiente manera:

this.appContextService.rpc.updateData(
    EnvironmentModule.nameOfShell,
    '##',
    <RpcUpdateData>{
        results: {
            connections: connections,
            credentials: this.useCredentials ? this.creds : null
        }
    }
);

El resultado es una propiedad de conexión, que es una matriz de objetos que se ajustan a la estructura siguiente:


/**
 * The connection attributes class.
 */
export interface ConnectionAttribute {

    /**
     * The id string of this attribute
     */
    id: string;

    /**
     * The value of the attribute. used for attributes that can have variable values such as Operating System
     */
    value?: string | number;
}

/**
 * The connection class.
 */
export interface Connection {

    /**
     * The id of the connection, this is unique per connection
     */
    id: string;

    /**
     * The type of connection
     */
    type: string;

    /**
     * The name of the connection, this is unique per connection type
     */
    name: string;

    /**
     * The property bag of the connection
     */
    properties?: ConnectionProperties;

    /**
     * The ids of attributes identified for this connection
     */
    attributes?: ConnectionAttribute[];

    /**
     * The tags the user(s) have assigned to this connection
     */
    tags?: string[];
}

/**
 * Defines connection type strings known by core
 * Be careful that these strings match what is defined by the manifest of @msft-sme/server-manager
 */
export const connectionTypeConstants = {
    server: 'msft.sme.connection-type.server',
    cluster: 'msft.sme.connection-type.cluster',
    hyperConvergedCluster: 'msft.sme.connection-type.hyper-converged-cluster',
    windowsClient: 'msft.sme.connection-type.windows-client',
    clusterNodesProperty: 'nodes'
};

Definición de onCancel

onCancel cancela un intento de "Agregar conexión" pasando una matriz de conexiones vacía:

this.appContextService.rpc.updateData(EnvironmentModule.nameOfShell, '##', <RpcUpdateData>{ results: { connections: [] } });

Ejemplo de proveedor de conexión

A continuación se muestra la clase TypeScript completa para implementar un proveedor de conexión. Tenga en cuenta que la cadena "connectionType" coincide con "connectionType, como se define en el proveedor de conexiones en manifest.json.

import { Component, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { AppContextService } from '@microsoft/windows-admin-center-sdk/shell/angular';
import { Connection, ConnectionUtility } from '@microsoft/windows-admin-center-sdk/shell/core';
import { EnvironmentModule } from '@microsoft/windows-admin-center-sdk/shell/dist/core/manifest/environment-modules';
import { RpcUpdateData } from '@microsoft/windows-admin-center-sdk/shell/dist/core/rpc/rpc-base';
import { Strings } from '../../generated/strings';

@Component({
  selector: 'add-example',
  templateUrl: './add-example.component.html',
  styleUrls: ['./add-example.component.css']
})
export class AddExampleComponent implements OnInit {
  public newConnectionName: string;
  public strings = MsftSme.resourcesStrings<Strings>().SolutionExample;
  private connectionType = 'msft.sme.connection-type.example'; // This needs to match the connectionTypes value used in the manifest.json.

  constructor(private appContextService: AppContextService, private route: ActivatedRoute) {
    // TODO:
  }

  public ngOnInit() {
    // TODO
  }

  public onSubmit() {
    let connections: Connection[] = [];

    let connection = <Connection> {
      id: ConnectionUtility.createConnectionId(this.connectionType, this.newConnectionName),
      type: this.connectionType,
      name: this.newConnectionName
    };

    connections.push(connection);

    this.appContextService.rpc.updateData(
      EnvironmentModule.nameOfShell,
      '##',
      <RpcUpdateData> {
        results: {
          connections: connections,
          credentials: null
        }
      }
    );
  }

  public onCancel() {
    this.appContextService.rpc.updateData(
      EnvironmentModule.nameOfShell, '##', <RpcUpdateData>{ results: { connections: [] } });
  }
}

Compartir a través de