다음을 통해 공유

솔루션 확장에 대한 연결 공급자 생성

  • 아티클
  • 적용 대상:
    ✅ Windows Admin Center, ✅ Windows Admin Center Preview

연결 공급자는 Windows Admin Center에서 연결 가능한 개체 또는 대상을 정의하고 통신하는 방법에서 중요한 역할을 합니다. 연결 공급자는 연결이 이루어지는 동안 주로 대상을 온라인 상태로 사용할 수 있는지 확인하고 연결 사용자에게 대상에 액세스할 수 있는 권한이 있는지 확인하는 등의 작업을 수행합니다.

기본적으로 Windows Admin Center는 다음 연결 공급자와 함께 제공됩니다.

  • 서버
  • Windows 클라이언트
  • 장애 조치(Failover) 클러스터
  • 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 셸에 나타냅니다. 연결 공급자 진입점에는 아래에 정의된 바와 같이 여러 중요한 속성이 포함되어 있습니다.

속성 설명
entryPointType 다음은 필수 속성입니다. 유효한 세 가지 값은 "tool", "solution" 및 "connectionProvider"입니다.
이름 솔루션 범위 내에서 연결 공급자를 식별하세요. 이 값은 전체 Windows Admin Center 인스턴스 내에서 고유해야 합니다(솔루션에만 국한하지 않음).
경로 솔루션에서 구성할 경우 "연결 추가" UI의 URL 경로를 나타냅니다. 해당 값은 app-routing.module.ts 파일에 구성된 경로에 매핑되어야 합니다. 솔루션 진입점이 rootNavigationBehavior 연결을 사용하도록 구성되었다면 이 경로는 셸에서 연결 추가 UI를 표시하는 데 사용하는 모듈을 로드합니다. 자세한 내용은 rootNavigationBehavior 섹션에서 확인하세요.
displayName 여기에 입력한 값은 사용자가 솔루션의 연결 페이지를 로드할 때 검은색 Windows Admin Center 표시줄 아래의 셸 오른쪽에 표시됩니다.
아이콘 솔루션 드롭다운 메뉴에서 솔루션을 나타내는 데 사용되는 아이콘을 나타냅니다.
description 진입점에 대한 간단한 설명을 입력하세요.
connectionType 공급자가 로드할 연결 형식을 나타냅니다. 여기에 입력한 값은 솔루션 진입점에서도 솔루션이 해당 연결을 로드할 수 있도록 지정하는 데 사용됩니다. 여기에 입력한 값은 도구 진입점에서도 도구가 이 형식과 호환됨을 나타내는 데 사용됩니다. 여기에 입력한 해당 값은 애플리케이션 계층 구현 단계에서 "창 추가"의 RPC 호출에 제출되는 연결 개체에도 사용됩니다.
connectionTypeName 연결 테이블에서 연결 공급자를 사용하는 연결을 나타내는 데 사용됩니다. 이는 형식의 복수형 이름이 될 것으로 예상됩니다.
connectionTypeUrlName Windows Admin Center가 인스턴스에 연결된 후 로드된 솔루션을 표시하는 URL을 만드는 데 사용됩니다. 이 항목은 연결 후에 대상 앞에 사용됩니다. 해당 예제에서 "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 연결 상태 공급자 - 대상이 온라인 상태이고 나머지 호출을 통해 액세스할 수 있는지 확인하세요. 결과는 아래에 정의된 단일 속성인 "status"가 있는 개체에서 반환되어야 합니다.

상태 정의

연결 상태 공급자는 다음 형식을 따르는 단일 속성인 status이 있는 개체를 반환해야 합니다.

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

상태 속성:

  • 레이블 - 상태 반환 형식을 설명하는 레이블입니다. 레이블 값은 런타임에 매핑할 수 있음을 확인하시길 바랍니다. 런타임의 매핑 값은 아래 항목을 참조하세요.

  • 형식 - 상태 반환 형식입니다. 해당 형식은 다음과 같은 열거형 값을 가집니다. 2 이상의 값에 대해 플랫폼은 연결된 개체로 이동하지 않으며 UI에 오류가 표시됩니다.

    형식:

    값 설명
    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"가 있는 개체에서 반환되어야 합니다. RelativeGatewayUrl의 manifest.json 예제 연결 공급자 항목은 다음과 같습니다.

    {
      "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를 기준으로 합니다. URL에 $connectionName 있으면 연결 이름으로 바뀝니다.
  • 게이트웨이 확장을 생성하여 수행할 수 있는 호스트 게이트웨이에 대해 모든 relativeGatewayUrl 속성을 실행해야 합니다.

런타임에서 값 매핑

상태 반환 개체의 레이블 및 세부 정보 값은 공급자의 "defaultValueMap" 속성에 키와 값을 포함하여 튜닝 시간에 서식을 지정할 수 있습니다.

예를 들어 아래 값을 추가하면 "defaultConnection_test"가 레이블 또는 세부 정보에 대한 값으로 표시될 때마다 Windows Admin Center에서 자동으로 키를 구성된 리소스 문자열 값으로 바꿉니다.

    "defaultConnection_test": "resources:strings:addServer_status_defaultConnection_label"

애플리케이션 계층에서 연결 공급자 구현

이제 OnInit을 구현하는 TypeScript 클래스를 생성해 애플리케이션 계층에서 연결 공급자를 구현하겠습니다. 클래스에는 다음과 같은 기능이 있습니다.

함수 설명
생성자(private appContextService: AppContextService, private route: 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" 문자열은 manifest.json 연결 공급자에 정의된 "connectionType"과 일치합니다.

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: [] } });
  }
}