Visual Studio 명령 추가하기
클래스에서 Command
나타내는 명령은 사용자가 메뉴 항목을 선택하거나 도구 모음 단추를 누르거나 바로 가기 키를 입력하는 경우와 같이 사용자가 시작할 수 있는 몇 가지 작업입니다. 명령에는 표시 이름, 작업을 수행하는 실행 메서드(ExecuteCommandAsync
), 명령을 식별하는 도구 모음에 표시할 아이콘 및 사용자에게 명령을 설명하는 도구 설명이 있습니다. 다양한 조건에 따라 명령을 사용하거나 사용하지 않도록 설정할 수 있습니다.
새 확장성 모델의 명령은 비동기적으로 실행되므로 명령이 실행되는 동안 사용자가 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),
};
명령 아이콘에 사용자 지정 이미지 사용
다음 단계에 따라 사용자 지정 모니커를 사용하여 참조할 수 있는 사용자 지정 이미지를 추가할 수 있습니다.
- 이미지 소스 파일의 이름을
%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 이 사용됩니다.
- 예를 들어 MyImage.16.16.png (16*16png), MyImage.20.20.png (20*20png) 및 MyImage.xaml 은 모두 원본
- 모든 이미지 원본 파일을 폴더 아래에 배치합니다
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에서 명령을 양육하는 예제를 참조하세요.