Criar um provedor de conexão para uma extensão de solução

Artigo
04/12/2023

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

Os Provedores de Conexão desempenham um papel importante na forma como o Windows Admin Center define e se comunica com objetos conectáveis, ou destinos. Em princípio, um Provedor de Conexão executa ações enquanto uma conexão está sendo feita, como garantir que o destino esteja online e disponível e também garantir que o usuário conectado tenha permissão para acessar o destino.

Por padrão, o Windows Admin Center é fornecido com os seguintes Provedores de Conexão:

Servidor
Windows Client
Cluster de failover
Cluster HCI

Para criar seu Provedor de Conexão personalizado, siga estas etapas:

Adicionar detalhes do Provedor de Conexão a manifest.json
Definir o provedor de status de conexão
Implementar o Provedor de Conexão na camada de aplicativo

Adicionar detalhes do Provedor de Conexão a manifest.json

Agora, vamos examinar o que você precisa saber para definir um Provedor de Conexão no arquivo manifest.json do projeto.

Criar entrada em manifest.json

O arquivo manifest.json está localizado na pasta \src e contém, entre outras coisas, definições de pontos de entrada no projeto. Os tipos de pontos de entrada incluem Ferramentas, Soluções e Provedores de Conexão. Definiremos um Provedor de Conexão.

Um exemplo de entrada de Provedor de Conexão em manifest.json está abaixo:

    {
      "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"
        }
      }
    },

Um ponto de entrada do tipo "connnectionProvider" indica ao shell do Windows Admin Center que o item que está sendo configurado é um provedor que será usado por uma Solução para validar um estado de conexão. Os pontos de entrada do Provedor de Conexão contêm várias propriedades importantes, definidas abaixo:

Propriedade	Descrição
entryPointType	Esta é uma propriedade obrigatória. Há três valores válidos: "tool", "solution" e "connectionProvider".
name	Identifica o Provedor de Conexão dentro do escopo de uma Solução. Esse valor precisa ser exclusivo dentro de uma instância do Windows Admin Center completa (não apenas uma Solução).
caminho	Representa o caminho da URL para a interface do usuário "Adicionar Conexão", se ela for ser configurada pela Solução. Esse valor precisa ser mapeado para uma rota configurada no arquivo app-routing.module.ts. Quando o ponto de entrada de Solução estiver configurado para usar o rootNavigationBehavior das conexões, essa rota carregará o módulo usado pelo Shell para exibir a interface do usuário Adicionar Conexão. Mais informações estão disponíveis na seção sobre rootNavigationBehavior.
displayName	O valor inserido aqui é exibido no lado direito do shell, abaixo da barra preta do Windows Admin Center, quando um usuário carrega a página de conexões de uma Solução.
ícone	Representa o ícone usado no menu suspenso Soluções para representar a Solução.
descrição	Insira uma breve descrição do ponto de entrada.
connectionType	Representa o tipo de conexão que o provedor carregará. O valor inserido aqui também será usado no ponto de entrada da Solução para especificar que a Solução pode carregar essas conexões. O valor inserido aqui também será usado nos Pontos de entrada da ferramenta para indicar que a Ferramenta é compatível com esse tipo. O valor inserido aqui também será usado no objeto de conexão enviado à chamada RPC na "Janela Adicionar", na etapa de implementação da camada de aplicativo.
connectionTypeName	Usado na tabela de conexões para representar uma conexão que usa o Provedor de Conexão. Espera-se que esse seja o nome plural do tipo.
connectionTypeUrlName	Usado na criação da URL para representar a Solução carregada, depois que o Windows Admin Center se conectou a uma instância. Essa entrada é usada após as conexões e antes do destino. Neste exemplo, "connectionexample" é onde esse valor aparece na URL: `http://localhost:6516/solutionexample/connections/connectionexample/con-fake1.corp.contoso.com`
connectionTypeDefaultSolution	Representa o componente padrão que deve ser carregado pelo Provedor de Conexão. Esse valor é uma combinação de: [a] O nome do pacote de extensão definido na parte superior do manifesto; [b] Ponto de exclamação (!); [c] O nome do ponto de entrada da Solução. Para um projeto com o nome "msft.sme.mySample-extension" e um ponto de entrada da Solução com o nome "example", esse valor seria "msft.sme.solutionExample-extension!example".
connectionTypeDefaultTool	Representa a Ferramenta padrão que deve ser carregada em uma conexão bem-sucedida. Esse valor de propriedade é composto por duas partes, semelhante a connectionTypeDefaultSolution. Esse valor é uma combinação de: [a] O nome do pacote de extensão definido na parte superior do manifesto; [b] Ponto de exclamação (!); [c] O nome do ponto de entrada da Ferramenta que deve ser carregado inicialmente. Para um projeto com o nome "msft.sme.solutionExample-extension" e um ponto de entrada da Solução com o nome "example", esse valor seria "msft.sme.solutionExample-extension!example".
connectionStatusProvider	Consulte a seção "Definir o Provedor de Status de Conexão"

Definir o Provedor de Status de Conexão

O Provedor de Status de Conexão é o mecanismo pelo qual um destino é validado como estando online e disponível, garantindo também que o usuário conectado tenha permissão para acessar o destino. Atualmente, há dois tipos de Provedores de Status de Conexão: PowerShell e RelativeGatewayUrl.

Provedor de Status de Conexão do PowerShell – determina se um destino está online e acessível com um script do PowerShell. O resultado deve ser retornado em um objeto com uma propriedade "status", definida abaixo.
Provedor de Status de Conexão RelativeGatewayUrl – determina se um destino está online e acessível com uma chamada rest. O resultado deve ser retornado em um objeto com uma propriedade "status", definida abaixo.

Definir o status

Os Provedores de Status de Conexão precisam retornar um objeto com uma propriedade status que esteja em conformidade com o seguinte formato:

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

Propriedades de status:

Rótulo – um rótulo que descreve o tipo de retorno de status. Observe que os valores do rótulo podem ser mapeados em runtime. Consulte a entrada abaixo para obter os valores de mapeamento em runtime.
Tipo – o tipo de retorno de status. O tipo tem os valores de enumeração a seguir. Para qualquer valor 2 ou superior, a plataforma não navegará até o objeto conectado e um erro será exibido na interface do usuário.

Tipos:

Valor Descrição

0 Online

1 Aviso

2 Não Autorizado

3 Erro

4 Fatal

5 Unknown
Detalhes – detalhes adicionais que descrevem o tipo de retorno de status.

Valor	Descrição
0	Online
1	Aviso
2	Não Autorizado
3	Erro
4	Fatal
5	Unknown

Script do Provedor de Status de Conexão do PowerShell

O script do PowerShell do Provedor de Status de Conexão determina se um destino está online e acessível com um script do PowerShell. O resultado deve ser retornado em um objeto com uma propriedade "status". Um script de exemplo é mostrado abaixo.

Exemplo de script do 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

Definir o método RelativeGatewayUrl do Profissional de Status de Conexão

O método RelativeGatewayUrl do Provedor de Status de Conexão chama uma API rest para determinar se um destino está online e acessível. O resultado deve ser retornado em um objeto com uma propriedade "status". Um exemplo de entrada de Provedor de Conexão no manifest.json de um RelativeGatewayUrl é mostrado abaixo.

    {
      "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"
        }
      }
    },

Observações sobre o uso de RelativeGatewayUrl:

"relativeGatewayUrl" especifica onde obter o status da conexão de uma URL de gateway. Esse URI é relativo a /api. Se $connectionName for encontrado na URL, ele será substituído pelo nome da conexão.
Todas as propriedades relativeGatewayUrl precisam ser executadas no gateway de host, o que pode ser feito criando uma extensão de gateway

Mapear valores no runtime

Os valores de rótulo e detalhes no objeto de retorno de status podem ser formatados no momento do ajuste, incluindo chaves e valores na propriedade "defaultValueMap" do provedor.

Por exemplo, se você adicionar o valor abaixo, sempre que "defaultConnection_test" aparecer como um valor para rótulo ou detalhes, o Windows Admin Center substituirá automaticamente a chave pelo valor de cadeia de caracteres de recurso configurado.

    "defaultConnection_test": "resources:strings:addServer_status_defaultConnection_label"

Implementar o Provedor de Conexão na camada de aplicativo

Agora, vamos implementar o Provedor de Conexão na camada de aplicativo, criando uma classe TypeScript que implementa OnInit. A classe tem as seguintes funções:

Função	Descrição
constructor(private appContextService: AppContextService, private route: ActivatedRoute)
public ngOnInit()
public onSubmit()	Contém lógica para atualizar o shell quando uma tentativa de adicionar uma conexão é feita
public onCancel()	Contém lógica para atualizar o shell quando uma tentativa de adicionar uma conexão é cancelada

Definir onSubmit

onSubmit emite uma chamada RPC de volta ao contexto do aplicativo para notificar o shell de "Adicionar Conexão". A chamada básica usa "updateData" da seguinte maneira:

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

O resultado é uma propriedade de conexão, que é uma matriz de objetos que estão em conformidade com a seguinte estrutura:


/**
 * 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'
};

Definir onCancel

onCancel cancela uma tentativa de "Adicionar Conexão" passando uma matriz de conexões vazia:

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

Exemplo do Provedor de Conexão

A classe TypeScript completa para implementar um provedor de conexão está abaixo. Observe que a cadeia de caracteres "connectionType" corresponde ao "connectionType" conforme definido no provedor de conexão em 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: [] } });
  }
}

Compartilhar via