Visual Studio 명령 추가하기

클래스에서 Command 나타내는 명령은 사용자가 메뉴 항목을 선택하거나 도구 모음 단추를 누르거나 바로 가기 키를 입력하는 경우와 같이 사용자가 시작할 수 있는 몇 가지 작업입니다. 명령에는 표시 이름, 작업을 수행하는 실행 메서드(ExecuteCommandAsync), 명령을 식별하는 도구 모음에 표시할 아이콘 및 사용자에게 명령을 설명하는 도구 설명이 있습니다. 다양한 조건에 따라 명령을 사용하거나 사용하지 않도록 설정할 수 있습니다.

새 확장성 모델의 명령은 비동기적으로 실행되므로 명령이 실행되는 동안 사용자가 IDE와 계속 상호 작용할 수 있습니다.

명령 작업

이 개요에서는 명령을 사용하기 위한 다음과 같은 주요 시나리오에 대해 설명합니다.

• 명령 만들기
• IDE에 명령어를 입력합니다
• 명령에 아이콘 추가
• 명령에 단축키 추가
• 구성 명령
• 명령의 표시 이름 변경

명령 만들기

새 확장성 모델을 사용하여 명령을 만드는 것은 기본 클래스를 확장하고, 클래스 Command를 특성으로 VisualStudioContribution 표시하고, 속성을 구현하는 것으로 CommandConfiguration 시작합니다.

[VisualStudioContribution]
public class MyCommand : Command
{
  /// <inheritdoc />
  public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%");
}

CommandConfiguration 클래스

이 CommandConfiguration 클래스에는 익숙해져야 하는 몇 가지 매개 변수가 있습니다.

매개 변수	Type	필수	설명
DisplayName	String	예	명령의 기본 표시 이름입니다. 이 문자열을 '%' 문자로 묶어 이 문자열을 지역화할 수 있도록 합니다. 메타데이터 지역화를 참조하세요.
ToolTipText	문자열	아니요	명령이 가리키거나 포커스가 있을 때 도구 설명으로 표시할 텍스트입니다. 이 문자열을 '%' 문자로 묶어 이 문자열을 지역화할 수 있도록 합니다. 메타데이터 지역화를 참조하세요
플래그	CommandFlags	아니요	명령에 추가 속성을 설정하는 플래그입니다. 일부 옵션에는 CanToggle 및 CanSelect가 포함됩니다. 명령 플래그에서 참조하세요.
배치	명령 배치[]	아니요	명령을 부모로 지정할 Visual Studio 내의 기존 그룹을 지정합니다. IDE에서 명령 배치를 참조하세요. 배치가 없더라도 Visual Studio Search 기능을 통해 명령을 계속 사용할 수 있습니다. 확장에 정의된 메뉴, 도구 모음 및 그룹에 명령을 배치할 수도 있습니다.
Icon	CommandIconConfiguration	아니요	명령은 아이콘, 텍스트가 있는 아이콘 또는 텍스트로 UI에 표시할 수 있습니다. 이 속성은 해당 아이콘이 무엇인지, 있는 경우 및 표시 방법을 구성합니다.
바로 가기	CommandShortcutConfiguration[]	아니요	명령을 실행하는 데 사용할 수 있는 키 조합 집합을 정의합니다. 바로 가기 범위는 특정 IDE 컨텍스트에만 적용되도록 지정할 수 있습니다. 단축키 를참조하십시오.
ClientContexts[]	문자열	아니요	명령에서 요청한 클라이언트 컨텍스트입니다. 기본적으로 셸 및 편집기 컨텍스트가 반환됩니다. 클라이언트 컨텍스트는 명령이 처음 실행되었을 때 특정 IDE 상태의 스냅샷. 이러한 명령은 비동기적으로 실행되므로 사용자가 명령을 실행한 시간과 명령 처리기가 실행되는 시간 사이에 이 상태가 변경될 수 있습니다. 클라이언트 컨텍스트를 참조하세요.

예시

이 Command 은 또한 VisualStudioExtensibility 객체(IDE와의 통신을 허용하는)를 취하는 생성자와 실행 방법 ExecuteCommandAsync이 필요합니다. 다음 예제에서는 아무 작업도 수행하지 않는 제네릭 명령의 최소 구현을 제공합니다.

[VisualStudioContribution]
public class MyCommand : Command
{
    /// <inheritdoc />
    public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%");

    public MyCommand(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
    }

    public override Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
}

IDE에 명령어를 입력합니다

Visual Studio에는 명령을 배치할 수 있는 잘 정의된 위치 집합이 있습니다. 이러한 배치는 클래스 CommandPlacement의 속성 KnownPlacements 에 의해 정의됩니다. KnownPlacements 의 현재 세트는 다음과 같습니다:

• ToolsMenu - 명령은 Visual Studio의 최상위 "도구" 메뉴 아래에 있는 그룹에 배치됩니다.
• ViewOtherWindowsMenu - Visual Studio의 최상위 "보기" -> "기타 창" 메뉴 아래의 그룹에 명령이 배치됩니다.
• ExtensionsMenu - 명령은 Visual Studio의 최상위 "확장" 메뉴 아래에 있는 그룹에 배치됩니다.

VSCT를 통해 정의된 그룹의 Guid 및 Id 을 지정하여 CommandPlacement.VsctParent 방법을 사용하여 명령을 배치할 수도 있습니다.

동일한 그룹에 부모로 지정된 명령은 배치가 동일한 다른 명령 또는 메뉴를 기준으로 배치의 Priority 속성에 따라 정렬됩니다. CommandPlacement 의 기본 Priority 값은 0 이며, 원하는 Priority 값을 입력하고 CommandPlacement.WithPriority 메서드를 호출하여 수정할 수 있습니다.

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    // The command will be parented to a group inside of the "Tools" top level menu,
    // a group inside of the "Extensions" top level menu, and the "About" group inside of the "Help" top level menu
    Placements = new CommandPlacement[]
    {
        CommandPlacement.KnownPlacements.ToolsMenu,
        CommandPlacement.KnownPlacements.ExtensionsMenu.WithPriority(0x0100),
        CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x016B, priority: 0x0801),
    },
};

명령에 아이콘 추가

명령은 명령의 표시 이름 외에 또는 그 대신 메뉴 항목에 아이콘을 추가할 수 있도록 지원합니다. 명령에 아이콘을 추가하려면 명령의 Icon 속성을 CommandConfiguration설정합니다.

CommandIconConfiguration

이 CommandIconConfiguration 에는 다음 두 개의 매개 변수가 사용됩니다.

매개 변수	Type	필수	설명
IconName	ImageMoniker	예	이 사용자 지정 이미지 추가 섹션 다음에 추가한 이미지에 사용자 지정 식별자를 사용하거나 ImageMonikers.KnownValues.AddItem와 같은 Visual Studio ImageMoniker를 참조할 수 있습니다
IconSettings	IconSettings	예	명령이 표시되는 방법을 구성합니다. 예를 들어 IconSettings.IconAndText 명령의 표시 이름과 함께 아이콘을 표시하는 반면 IconSettings.IconOnly , 도구 모음에 부모가 있는 경우에는 해당 DisplayName이 아니라 명령의 아이콘만 표시됩니다.

ImageMoniker.KnownValues 예제

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Icon = new CommandIconConfiguration(ImageMoniker.KnownValues.Extension, IconSettings.IconAndText),
};

명령 아이콘에 사용자 지정 이미지 사용

다음 단계에 따라 사용자 지정 모니커를 사용하여 참조할 수 있는 사용자 지정 이미지를 추가할 수 있습니다.

1. 이미지 소스 파일의 이름을 %Custom Moniker%.* 패턴에 따르도록 변경합니다(예: MyImage.1.png). 동일한 모니커 접두사로 접두사로 지정된 파일은 모두 동일한 사용자 지정 모니커에 대한 백업 원본으로 사용됩니다. 요청된 아이콘 크기에 따라 다른 원본이 사용됩니다.
   • 예를 들어 MyImage.16.16.png (16*16png), MyImage.20.20.png (20*20png) 및 MyImage.xaml 은 모두 원본 MyImage으로 간주됩니다.
   • 요청된 아이콘 크기가 16*16이 면 MyImage.16.16.png 사용되며, 요청된 크기가 20*20이 면 MyImage.20.20.png 사용되며, 다른 모든 경우에는 MyImage.xaml 이 사용됩니다.
2. 모든 이미지 원본 파일을 폴더 아래에 배치합니다 Images .
   • 기본 이미지 자산 폴더는 Images, 이지만 추가하여 사용자 지정할 수도 있습니다. <ImageAssetsPath>%YourFolder%</ImageAssetsPath>

ImageMoniker.Custom 예제

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Icon = new CommandIconConfiguration(ImageMoniker.Custom("MyImage"), IconSettings.IconAndText),
};

바로 가기

특정 키 조합을 사용할 때 명령을 실행하도록 구성할 수 있습니다. 바로 가기는 하나 또는 두 개의 코드로 구성됩니다. 여기서 각 코드는 하나의 ModifierKey 코드로 Key구성됩니다. ModifierKey 의 가능한 값은 LeftAlt, Shift, Control, ControlShift, ControlShiftLeftAlt 및 None이며, 여기서 None 은 단축 코드의 두 번째 화음에서만 사용할 수 있습니다. 이 ModifierKey 바로 가기에서 두 코드 모두에 동일한 코드를 사용할 필요는 없습니다. 이 Key 코드에 사용되는 거의 모든 다른 키보드 키가 될 수 있습니다.

Visual Studio에서는 이미 다양한 바로 가기 키가 사용되고 있습니다. 중복 바인딩을 검색하기 어렵고 중복 바인딩으로 인해 예측할 수 없는 결과가 발생할 수 있으므로 두 개 이상의 명령에 동일한 바로 가기를 할당하면 안 됩니다. 따라서 바로 가기를 할당하기 전에 바로 가기 가용성을 확인하는 것이 좋습니다.

바로 가기 활성화 제약 조건

다른 컨텍스트에서 바로 가기를 사용할 수 있도록 구성에 활성화 제약 조건을 포함할 수 있습니다. 이러한 활성화 제약 조건은 Guid 형태로 정의되며 일반적으로 편집기와 관련이 있습니다. 바로 가기에 활성화 제약 조건이 지정되면 해당 특정 컨텍스트에서만 사용할 수 있습니다. 예를 들어 Visual Studio 편집기에서 바로 가기를 Guid 사용할 수 있도록 "{5EFC7975-14BC-11CF-9B2B-00AA00573819}"를 사용합니다. 이 경우 바로 가기는 Visual Studio 편집기가 포커스가 있는 경우에만 사용할 수 있습니다.

바로 가기 샘플

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Shortcuts = new CommandShortcutConfiguration[]
    {
        new(ModifierKey.LeftAlt, Key.M),
        new(ModifierKey.ControlShift, Key.Y, ModifierKey.ControlShift, Key.B),
    },
};

구성 명령

명령의 표시 유형 및 사용/사용 안 함 상태를 구성하고 플래그를 사용하여 추가 메타데이터를 설정할 수 있습니다.

표시 유형

명령의 속성을 설정 VisibleWhen 하여 명령의 CommandConfiguration표시 유형을 제어할 수 있습니다.

이 특성은 조건과 모든 논리 및 입력을 함께 지정하는 여러 개별 매개 변수를 통해 조건 지정을 지원합니다. 조건을 지정하려면 한 매개 변수에서 식을 지정하고, 다른 매개 변수의 식에 사용되는 용어 집합(문자열)을 정의하고, 세 번째 매개 변수에서 평가 시 해당 용어를 대체해야 하는 값이 무엇인지 정의합니다. 식, 용어 및 값의 조합을 규칙 기반 활성화 제약 조건이라고 하며 규칙 기반 활성화 제약 조건에서 완전히 설명합니다.

구성에서 이 속성을 생략하면 기본값은 명령이 항상 표시되는 것입니다.

표시 유형 예제

public override CommandConfiguration CommandConfiguration => new("My command")
{
    VisibleWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.(jpg|jpeg|txt)$"),
};

사용/사용 안 함 상태

명령의 활성화/비활성화 상태는 명령의 CommandConfiguration에 EnabledWhen 속성을 설정하여 제어할 수 있습니다.

이러한 유형의 구성을 규칙 기반 활성화 제약 조건이라고 하며 규칙 기반 활성화 제약 조건 사용에 대해 완전히 설명 합니다.

이 구성이 명령에서 누락된 경우 기본적으로 명령이 항상 활성화됩니다. 명령 클래스의 생성자에서 설정 this.DisableDuringExecution = true; 하여 현재 실행 중인 경우 명령을 자동으로 사용하지 않도록 설정할 수도 있습니다. 이 속성을 설정하면 명령이 실행되는 동안 구성에서 EnabledWhen 정의한 사용/사용 안 함 상태가 재정의됩니다.

활성화/비활성화 상태 예제

public override CommandConfiguration CommandConfiguration => new("My command")
{
    EnabledWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.(jpg|jpeg|txt)$"),
};

유효한 항 값에 대한 자세한 내용은 규칙 기반 활성화 제약 조건를 참조하십시오.

명령 플래그

명령 플래그는 런타임에 명령에 사용할 수 있는 특수 동작을 정의하는 데 사용되는 명령에 대한 추가 속성을 정의하는 데 도움이 됩니다. 현재 지원되는 플래그는 다음과 같습니다:

• CanToggle - 화면 읽기 프로그램이 명령을 제대로 알릴 수 있도록 명령의 속성이 변경 될 수 있음을 나타냅니다 IsChecked . 기능적으로 자동화 속성 IsTogglePatternAvailable 이 UI 요소에 대해 true를 반환하도록 합니다.
• CanSelect - 화면 읽기 프로그램이 명령을 제대로 알릴 수 있도록 명령의 속성이 변경 될 수 있음을 나타냅니다 IsChecked . 기능적으로 자동화 속성 IsSelectionPatternAvailable 이 UI 요소에 대해 true를 반환하도록 합니다.

명령의 표시 이름 변경

명령의 표시 이름은 초기에 CommandConfiguration 에서 설정되어 있지만( 명령어 생성참조), 실행 시 명령에서 DisplayName 속성을 설정하여 변경할 수 있습니다. 속성은 ToolTipText 비슷한 방식으로 업데이트할 수 있습니다.

DisplayName 예제 변경

[VisualStudioContribution]
public class MyCommand : Command
{
    /// <inheritdoc />
    public override CommandConfiguration CommandConfiguration => new("Initial Display Name");

    public MyCommand(VisualStudioExtensibility extensibility)
     : base(extensibility)
    {
    }

    public override Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        // Update the command's Display Name
        this.DisplayName = "Updated Display Name";
        return Task.CompletedTask;
    }
}

다음 단계

• 시작 섹션의 프로젝트 만들기 섹션을 따릅니다.
• 메뉴 및 도구 모음 구성에 대한 설명서 살펴보기
• 다음으로, 명령을 사용하여 확장을 만드는 방법에 대한 자세한 내용은 InsertGuidSample 샘플을 참조하세요.
• CommandParentingSample에서 명령을 양육하는 예제를 참조하세요.