Создание поставщика подключений для расширения решения

Статья
11/02/2024
Применяется к:

✅ Windows Admin Center, ✅ Windows Admin Center Preview

Поставщики подключений играют важную роль в том, как Windows Admin Center определяет и взаимодействует с подключенными объектами или целевыми объектами. В первую очередь поставщик подключений выполняет действия во время выполнения подключения, например обеспечение доступности целевого объекта в сети и обеспечение доступа к целевому объекту.

По умолчанию Windows Admin Center поставляется со следующими поставщиками подключений:

Сервер
Клиент Windows
Кластер отказоустойчивости
Кластер HCI

Чтобы создать собственный настраиваемый поставщик подключений, выполните следующие действия.

Добавление сведений о поставщике подключений в manifest.json
Определение поставщика состояния подключения
Реализация поставщика подключений на уровне приложений

Добавление сведений о поставщике подключений в manifest.json

Теперь мы рассмотрим, что необходимо знать, чтобы определить поставщика подключений в файле проекта manifest.json .

Создание записи в manifest.json

Файл manifest.json находится в папке \src и содержит, помимо прочего, определения точек входа в проект. Типы точек входа включают средства, решения и поставщики подключений. Мы определим поставщика подключений.

Ниже приведен пример записи поставщика подключений в 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"
        }
      }
    },

Точка входа типа connnectionProvider указывает на оболочку Windows Admin Center, что настроенный элемент является поставщиком, который будет использоваться решением для проверки состояния подключения. Точки входа поставщика подключений содержат ряд важных свойств, определенных ниже.

Свойство	Description
entryPointType	Это обязательное свойство. Существует три допустимых значения: "tool", "solution" и "connectionProvider".
name	Определяет поставщика подключений в области решения. Это значение должно быть уникальным внутри полного экземпляра Windows Admin Center (а не только решения).
path	Представляет путь URL-адреса для пользовательского интерфейса "Добавить подключение", если он будет настроен решением. Это значение должно сопоставляться с маршрутом, настроенным в файле app-routing.module.ts. Когда точка входа решения настроена для использования подключений rootNavigationBehavior, этот маршрут загружает модуль, используемый оболочкой для отображения пользовательского интерфейса добавления подключения. Дополнительные сведения см. в разделе rootNavigationBehavior.
displayName	Введенное здесь значение отображается справа от оболочки под черной панелью Центра администрирования Windows, когда пользователь загружает страницу подключений решения.
значок	Представляет значок, используемый в раскрывающемся меню "Решения" для представления решения.
описание	Введите краткое описание точки входа.
connectionType	Представляет тип подключения, который будет загружать поставщик. Введенное здесь значение также будет использоваться в точке входа решения, чтобы указать, что решение может загружать эти подключения. Введенное здесь значение также будет использоваться в точках входа инструмента, чтобы указать, что средство совместимо с этим типом. Это значение, введенное здесь, также будет использоваться в объекте подключения, отправленном вызову RPC на шаге реализации уровня приложения.
connectionTypeName	Используется в таблице подключений для представления подключения, использующего поставщика подключений. Ожидается, что это будет множественное имя типа.
connectionTypeUrlName	Используется при создании URL-адреса для представления загруженного решения после подключения Windows Admin Center к экземпляру. Эта запись используется после подключений и перед целевым объектом. В этом примере "connectionexample" отображается в URL-адресе: `http://localhost:6516/solutionexample/connections/connectionexample/con-fake1.corp.contoso.com`
connectionTypeDefaultSolution	Представляет компонент по умолчанию, который должен загружаться поставщиком подключений. Это значение является сочетанием: [a] Имя пакета расширения, определенного в верхней части манифеста; [b] Восклицательный знак (!); [c] Имя точки входа решения. Для проекта с именем msft.sme.mySample-extension и точкой входа решения с именем "example", это значение будет "msft.sme.solutionExample-extension!example".
connectionTypeDefaultTool	Представляет средство по умолчанию, которое должно быть загружено на успешное подключение. Это значение свойства состоит из двух частей, аналогичных connectionTypeDefaultSolution. Это значение является сочетанием: [a] Имя пакета расширения, определенного в верхней части манифеста; [b] Восклицательный знак (!); [c] Имя точки входа средства для инструмента, которое должно быть загружено изначально. Для проекта с именем msft.sme.solutionExample-extension и точкой входа решения с именем example это значение будет "msft.sme.solutionExample-extension!example".
connectionStatusProvider	См. раздел "Определение поставщика состояния подключения"

Определение поставщика состояния подключения

Поставщик состояния подключения — это механизм, с помощью которого целевой объект проверяется в сети и доступен, а также гарантирует, что у подключающегося пользователя есть разрешение на доступ к целевому объекту. В настоящее время существует два типа поставщиков состояния подключения: PowerShell и RelativeGatewayUrl.

Поставщик состояния подключения PowerShell— определяет, подключен ли целевой объект к сети и доступен с помощью скрипта PowerShell. Результат должен быть возвращен в объекте с одним свойством "status", определенным ниже.
Поставщик состояния подключения RelativeGatewayUrl— определяет, находится ли целевой объект в сети и доступен с помощью rest вызова. Результат должен быть возвращен в объекте с одним свойством "status", определенным ниже.

Определение состояния

Поставщики состояния подключения должны возвращать объект с одним свойством status , соответствующим следующему формату:

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

Свойства состояния:

Метка — метка , описывающая тип возвращаемого состояния. Обратите внимание, что значения метки можно сопоставить в среде выполнения. См. запись ниже для сопоставления значений во время выполнения.

Тип — тип возвращаемого состояния. Тип имеет следующие значения перечисления. Для любого значения 2 или более поздней платформы платформа не перейдет к подключенному объекту, и в пользовательском интерфейсе будет отображаться ошибка.

Типы:

значение	Описание
0	Миграция по сети
1	Предупреждение
2	Не авторизовано
3	Ошибка
4	Смертельно
5	Неизвестно

Сведения — дополнительные сведения, описывающие тип возвращаемого состояния.

Скрипт поставщика состояния подключения PowerShell

Сценарий PowerShell поставщика состояния подключения определяет, доступен ли целевой объект в сети и доступен с помощью скрипта PowerShell. Результат должен быть возвращен в объекте с одним свойством "status". Ниже показан пример скрипта.

Пример скрипта 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

Определение метода поставщика состояния подключения RelativeGatewayUrl

Метод поставщика RelativeGatewayUrl состояния подключения вызывает rest API, чтобы определить, находится ли целевой объект в сети и доступен. Результат должен быть возвращен в объекте с одним свойством "status". Ниже показан пример записи поставщика подключений в manifest.json объекта 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"
        }
      }
    },

Заметки об использовании RelativeGatewayUrl:

"relativeGatewayUrl" указывает, где получить состояние подключения из URL-адреса шлюза. Этот универсальный код ресурса (URI) является относительным из /api. Если $connectionName найден в URL-адресе, оно будет заменено именем подключения.
Все относительные свойстваGatewayUrl должны выполняться в шлюзе узла, который можно выполнить путем создания расширения шлюза.

Сопоставление значений во время выполнения

Значения меток и сведений в объекте возвращаемого состояния можно отформатировать во время настройки, включив ключи и значения в свойство defaultValueMap поставщика.

Например, если вы добавите приведенное ниже значение, в любое время, когда "defaultConnection_test" отображалось в качестве значения метки или сведений, Windows Admin Center автоматически заменит ключ настроенным строковым значением ресурса.

    "defaultConnection_test": "resources:strings:addServer_status_defaultConnection_label"

Реализация поставщика подключений на уровне приложений

Теперь мы будем реализовывать поставщика подключений на уровне приложения, создав класс TypeScript, реализующий OnInit. Класс имеет следующие функции:

Function	Description
конструктор(private appContextService: AppContextService, частный маршрут: ActivatedRoute)
public ngOnInit()
public onSubmit()	Содержит логику обновления оболочки при попытке добавления подключения
public onCancel()	Содержит логику обновления оболочки при отмене попытки добавления подключения

Определение onSubmit

onSubmit выдает обратный вызов RPC в контекст приложения, чтобы уведомить оболочку "Добавить подключение". Базовый вызов использует updateData, как показано ниже.

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

Результатом является свойство подключения, которое является массивом объектов, которые соответствуют следующей структуре:


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

Определение onCancel

onCancel Отменяет попытку "Добавить подключение", передав пустой массив подключений:

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

Пример поставщика подключений

Ниже приведен полный класс TypeScript для реализации поставщика подключений. Обратите внимание, что строка connectionType соответствует "connectionType, как определено в поставщике подключений в 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: [] } });
  }
}

Поделиться через