구문 개요: 명령, 옵션 및 인수

중요합니다

System.CommandLine 는 현재 미리 보기로 제공되며, 이 설명서는 버전 2.0 베타 5용입니다. 일부 정보는 릴리스되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다.

System.CommandLine에서 인식하는 명령줄 구문을 이 문서에서 설명합니다. 이 정보는 .NET CLI를 포함하여 .NET 명령줄 앱의 사용자와 개발자 모두에게 유용합니다.

토큰

System.CommandLine 명령줄 입력을 공백으로 구분된 문자열인 토큰으로 구문 분석합니다. 예를 들어 다음 명령줄을 고려합니다.

dotnet tool install dotnet-suggest --global --verbosity quiet

이 입력은 dotnet 애플리케이션에서 tool, install, dotnet-suggest, --global, --verbosity, quiet 토큰으로 구문 분석됩니다.

토큰은 명령, 옵션 또는 인수로 해석됩니다. 호출되는 명령줄 앱은 첫 번째 토큰 이후의 토큰이 해석되는 방법을 결정합니다. 다음 표에서는 앞의 예제를 해석하는 방법을 System.CommandLine 보여 줍니다.

토큰	로 구문 분석됨
tool	하위 명령
install	하위 명령
dotnet-suggest	설치 명령에 대한 인수
--global	설치 명령에 대한 옵션
--verbosity	설치 명령에 대한 옵션
quiet	옵션에 대한 --verbosity 인수

토큰은 따옴표(")로 묶인 경우 공백을 포함할 수 있습니다. 예제는 다음과 같습니다.

dotnet tool search "ef migrations add"

명령어

명령줄 입력의 명령은 작업을 지정하거나 관련 작업 그룹을 정의하는 토큰입니다. 다음은 그 예입니다.

• dotnet run에서 run은(는) 작업을 지정하는 명령입니다.
• dotnet tool install 에서 install동작을 지정하는 명령이며 tool 관련 명령 그룹을 지정하는 명령입니다. 다른 도구 관련 명령(예: tool uninstall, tool list및 )이 있습니다 tool update.

루트 명령

루트 명령은 앱 실행 파일의 이름을 지정하는 명령입니다. 예를 들어 dotnet 명령은 dotnet.exe 실행 파일을 지정합니다.

System.CommandLine.Command는 모든 명령 또는 하위 명령에 대한 범용 클래스이지만, 도움말 System.CommandLine.RootCommand, System.CommandLine.Command버전 옵션 및 제안 지시문과 같은 루트별 동작 및 기본값을 추가하는 모든 기능을 상속하는 애플리케이션의 루트 진입점을 위한 특수 버전입니다.

하위 명령

대부분의 명령줄 앱은 동사라고도 하는 하위 명령을 지원합니다. 예를 들어 명령에는 dotnetrun 입력 dotnet run하여 호출하는 하위 명령이 있습니다.

하위 명령에는 자체 하위 명령이 있을 수 있습니다. dotnet tool install는 install의 tool 명령어 하위 명령입니다.

다음 예제와 같이 하위 명령을 추가할 수 있습니다.

RootCommand rootCommand = new();

Command sub1Command = new("sub1", "First-level subcommand");
rootCommand.Subcommands.Add(sub1Command);

Command sub1aCommand = new("sub1a", "Second level subcommand");
sub1Command.Subcommands.Add(sub1aCommand);

이 예제의 가장 안쪽 하위 명령은 다음과 같이 호출할 수 있습니다.

myapp sub1 sub1a

옵션

옵션은 명령에 전달할 수 있는 명명된 매개 변수입니다. POSIX CLI는 일반적으로 옵션 이름 앞에 두 개의 하이픈(--)을 추가합니다. 다음 예제에서는 두 가지 옵션을 보여줍니다.

dotnet tool update dotnet-suggest --verbosity quiet --global
                                  ^---------^       ^------^

이 예제에서 알 수 있듯이 옵션 값은 명시적(quiet 예 --verbosity: )이거나 암시적일 수 있습니다(아무것도 따르지 않음 --global). 지정된 값이 없는 옵션은 일반적으로 명령줄에 옵션이 지정된 경우 기본값 true 인 부울 매개 변수입니다.

일부 Windows 명령줄 앱의 경우 옵션 이름과 함께 선행 슬래시(/)를 사용하여 옵션을 식별합니다. 다음은 그 예입니다.

msbuild /version
        ^------^

System.CommandLine 는 POSIX 및 Windows 접두사 규칙을 모두 지원합니다.

옵션을 구성할 때 접두사를 포함하여 옵션 이름을 지정합니다.

Option<int> delayOption = new("--delay", "-d")
{
    Description = "An option whose argument is parsed as an int.",
    DefaultValueFactory = parseResult => 42,
};
Option<string> messageOption = new("--message", "-m")
{
    Description = "An option whose argument is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Options.Add(delayOption);
rootCommand.Options.Add(messageOption);

명령에 옵션을 추가하고 모든 하위 명령에 재귀적으로 추가하려면 이 속성을 사용합니다 System.CommandLine.Symbol.Recursive .

필수 옵션

일부 옵션에는 필수 인수가 있습니다. 예를 들어 .NET CLI --output 에서는 폴더 이름 인수가 필요합니다. 인수가 제공되지 않으면 명령이 실패합니다. 필요한 옵션을 만들려면 다음 예제와 같이 해당 System.CommandLine.Symbol.Required 속성을 true다음 예제와 같이 설정합니다.

Option<FileInfo> fileOption = new("--output")
{
    Required = true
};

필수 옵션에 기본값(속성을 통해 DefaultValueFactory 지정됨)이 있는 경우 명령줄에 옵션을 지정할 필요가 없습니다. 이 경우 기본값은 필요한 옵션 값을 제공합니다.

주장들

인수는 명령에 전달할 수 있는 명명되지 않은 매개 변수입니다. 다음 예제는 build 명령에 대한 인수를 보여줍니다.

dotnet build myapp.csproj
             ^----------^

인수를 구성할 때 인수 이름을 지정하고(구문 분석에는 사용되지 않지만 이름 또는 도움말 표시로 구문 분석된 값을 가져오는 데 사용할 수 있습니다. ) 다음을 입력합니다.

Argument<int> delayArgument = new("delay")
{
    Description = "An argument that is parsed as an int.",
    DefaultValueFactory = parseResult => 42
};
Argument<string> messageArgument = new("message")
{
    Description = "An argument that is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Arguments.Add(delayArgument);
rootCommand.Arguments.Add(messageArgument);

기본값

인수와 옵션 모두 명시적으로 제공된 인수가 없는 경우 적용되는 기본값을 가질 수 있습니다. 예를 들어 많은 옵션은 명령줄에 옵션 이름이 나타날 때 암시적으로 true 기본값을 가지는 부울 매개 변수입니다. 다음 명령줄 예제는 동일합니다.

dotnet tool update dotnet-suggest --global
                                  ^------^

dotnet tool update dotnet-suggest --global true
                                  ^-----------^

기본값 없이 정의된 인수는 필수 인수로 처리됩니다.

구문 분석 오류

옵션 및 인수에는 예상 형식이 있으며 값을 구문 분석할 수 없는 경우 오류가 발생합니다. 예를 들어 "silent"이 유효한 값 중 하나가 아니므로 다음 명령 오류가 발생합니다 --verbosity.

dotnet build --verbosity silent

Option<string> verbosityOption = new("--verbosity", "-v")
{
    Description = "Set the verbosity level.",
};
verbosityOption.AcceptOnlyFromAmong("quiet", "minimal", "normal", "detailed", "diagnostic");
RootCommand rootCommand = new() { verbosityOption };

ParseResult parseResult = rootCommand.Parse(args);
foreach (ParseError parseError in parseResult.Errors)
{
    Console.WriteLine(parseError.Message);
}

Argument 'silent' not recognized. Must be one of:
        'quiet'
        'minimal'
        'normal'
        'detailed'
        'diagnostic'

인수에는 제공할 수 있는 값 수에 대한 기대도 있습니다. 인수 진도 섹션에 예제가 제공됩니다.

옵션 및 인수 순서

옵션을 제시할 수도 있고 인수를 제시할 수도 있으며, 그 순서는 명령줄에서 옵션을 앞에 두거나 인수를 앞에 둘 수 있습니다. 다음 명령은 동일합니다.

dotnet add package System.CommandLine --prerelease
dotnet add package --prerelease System.CommandLine

옵션은 순서대로 지정할 수 있습니다. 다음 명령은 동일합니다.

dotnet add package System.CommandLine --prerelease --no-restore --source https://api.nuget.org/v3/index.json
dotnet add package System.CommandLine --source https://api.nuget.org/v3/index.json --no-restore --prerelease

인수가 여러 대 있는 경우 순서가 중요합니다. 다음 명령은 동일하지 않습니다. 값의 순서가 다르므로 결과가 다를 수 있습니다.

myapp argument1 argument2
myapp argument2 argument1

별칭

POSIX와 Windows 모두에서 일부 명령과 옵션에 별칭이 있는 것이 일반적입니다. 일반적으로 입력하기 쉬운 짧은 형식입니다. 별칭은 다른 목적으로도 사용할 수 있는데, 케이스 민감도를 시뮬레이션하거나 단어의 대체 철자를 지원하는 데 사용될 수 있습니다.

POSIX 짧은 폼에는 일반적으로 단일 선행 하이픈과 단일 문자가 있습니다. 다음 명령은 동일합니다.

dotnet build --verbosity quiet
dotnet build -v quiet

GNU 표준은 자동 별칭을 권장합니다. 즉, 긴 형식 명령 또는 옵션 이름의 일부를 입력할 수 있으며 허용됩니다. 이 동작은 다음 명령줄을 동일하게 만듭니다.

dotnet publish --output ./publish
dotnet publish --outpu ./publish
dotnet publish --outp ./publish
dotnet publish --out ./publish
dotnet publish --ou ./publish
dotnet publish --o ./publish

System.CommandLine 는 자동 별칭을 지원하지 않습니다. 각 별칭은 명시적으로 지정해야 합니다. 명령과 옵션 모두 속성을 노출합니다 Aliases . Option 에는 별칭을 매개 변수로 허용하는 생성자가 있으므로 한 줄에 여러 별칭이 있는 옵션을 정의할 수 있습니다.

Option<bool> helpOption = new("--help", ["-h", "/h", "-?", "/?"]);
Command command = new("serialize") { helpOption };
command.Aliases.Add("serialise");

정의하는 옵션 별칭의 수를 최소화하고 특정 별칭을 정의하지 않는 것이 좋습니다. 자세한 내용은 짧은 형식 별칭을 참조하세요.

대/소문자 구분

명령 및 옵션 이름 및 별칭은 POSIX 규칙에 따라 기본적으로 대/소문자를 구분하며 System.CommandLine 이 규칙을 따릅니다. CLI가 대/소문자를 구분하지 않도록 하려면 다양한 대/소문자 대체에 대한 별칭을 정의합니다. 예를 들어 --additional-probing-path는 --Additional-Probing-Path과 --ADDITIONAL-PROBING-PATH의 별칭을 가질 수 있습니다.

일부 명령줄 도구에서 대/소문자 구분의 차이는 기능의 차이를 의미합니다. 예를 들어, git clean -X은 git clean -x과 다르게 작동합니다. .NET CLI는 모두 소문자로 작성해야 합니다.

열거형을 기반으로 하는 옵션의 인수 값에는 대/소문자 구분이 적용되지 않습니다. 열거형 이름은 대/소문자 구분에 관계없이 일치합니다.

-- 토큰

POSIX 규칙은 이중 대시(--) 토큰을 이스케이프 메커니즘으로 해석합니다. 이중 대시 토큰 뒤에 있는 모든 항목은 명령에 대한 인수로 해석됩니다. 이 기능은 옵션으로 해석되지 않으므로 옵션처럼 보이는 인수를 제출하는 데 사용할 수 있습니다.

myapp이 message이라는 인수를 받는다고 가정하고, message의 값을 --interactive로 설정하려고 합니다. 다음 명령줄은 예기치 않은 결과를 제공할 수 있습니다.

myapp --interactive

옵션이 없 myapp 으면 --interactive 토큰이 --interactive 인수로 해석됩니다. 그러나 앱에 옵션이 있는 --interactive 경우 이 입력은 해당 옵션을 참조하는 것으로 해석됩니다.

다음 명령줄에서는 이중 대시 토큰을 사용하여 인수 값을 message "--interactive"로 설정합니다.

myapp -- --interactive
      ^^

System.CommandLine 는 이 이중 대시 기능을 지원합니다.

옵션-인수 구분 기호

System.CommandLine 에서는 옵션 이름과 해당 인수 사이의 구분 기호로 공백 '=', ':'를 사용할 수 있습니다. 예를 들어 다음 명령은 동일합니다.

dotnet build -v quiet
dotnet build -v=quiet
dotnet build -v:quiet

POSIX 규칙을 사용하면 단일 문자 옵션 별칭을 지정할 때 구분 기호를 생략할 수 있습니다. 예를 들어 다음 명령은 동일합니다.

myapp -vquiet
myapp -v quiet

System.CommandLine 는 기본적으로 이 구문을 지원합니다.

인수 개수

옵션 또는 명령 인수의 경도 는 해당 옵션 또는 명령이 지정된 경우 전달할 수 있는 값의 수입니다.

Arity는 다음 표와 같이 최소값과 최대값으로 표현됩니다.

민	맥스	유효성의 예	예시
0	0	유효한:	--파일
		올바르지 않음:	--file a.json
		올바르지 않음:	--file a.json --file b.json
0	1	유효한:	--플래그
		유효한:	--flag true
		유효한:	--flag false
		올바르지 않음:	--flag 거짓 --flag 거짓
1	1	유효한:	--file a.json
		올바르지 않음:	--파일
		올바르지 않음:	--file a.json --file b.json
0	n	유효한:	--파일
		유효한:	--file a.json
		유효한:	--file a.json --file b.json
1	n	유효한:	--file a.json
		유효한:	--file a.json b.json
		올바르지 않음:	--파일

System.CommandLine System.CommandLine.ArgumentArity 에는 다음 값을 사용하여 arity를 정의하기 위한 구조체가 있습니다.

• System.CommandLine.ArgumentArity.Zero - 허용되는 값이 없습니다.
• System.CommandLine.ArgumentArity.ZeroOrOne - 값이 하나일 수 있고 값이 없을 수 있습니다.
• System.CommandLine.ArgumentArity.ExactlyOne - 값이 하나 있어야 합니다.
• System.CommandLine.ArgumentArity.ZeroOrMore - 값 하나, 여러 값 또는 값이 없을 수 있습니다.
• System.CommandLine.ArgumentArity.OneOrMore - 값이 여러 개 있을 수 있으며 하나 이상의 값이 있어야 합니다.

속성을 사용하여 arity를 Arity 명시적으로 설정할 수 있지만 대부분의 경우 그럴 필요는 없습니다. System.CommandLine 는 인수 형식에 따라 인수 계수 값을 자동으로 결정합니다.

인수 형식	기본 인수 개수
Boolean	ArgumentArity.ZeroOrOne
컬렉션 형식	ArgumentArity.ZeroOrMore
기타 등등	ArgumentArity.ExactlyOne

옵션 재정의

System.CommandLine의 수용 가능 최대값이 1일 때에도 옵션의 여러 인스턴스를 허용하도록 구성할 수 있습니다. 이 경우 반복된 옵션의 마지막 인스턴스는 이전 인스턴스를 덮어씁니다. 다음 예제에서는 값 2가 명령에 전달됩니다 myapp .

myapp --delay 3 --message example --delay 2

여러 인수

기본적으로 명령을 호출할 때 옵션 이름을 반복하여 최대 진도가 1보다 큰 옵션에 대해 여러 인수를 지정할 수 있습니다.

myapp --items one --items two --items three

옵션 이름을 반복하지 않고 여러 인수를 허용하려면 System.CommandLine.Option.AllowMultipleArgumentsPerToken을 true으로 설정합니다. 이 설정을 사용하면 다음 명령줄을 입력할 수 있습니다.

myapp --items one two three

최대 인수 크기가 1인 경우 동일한 설정에 다른 효과가 있습니다. 옵션을 반복할 수 있지만 줄의 마지막 값만 사용합니다. 다음 예제에서는 값 three 이 앱에 전달됩니다.

myapp --item one --item two --item three

옵션 번들링

POSIX는 스택이라고도 하는 단일 문자 옵션의 묶음을 지원하는 것이 좋습니다. 번들 옵션은 단일 하이픈 접두사 다음에 함께 지정된 단일 문자 옵션 별칭입니다. 마지막 옵션만 인수를 지정할 수 있습니다. 예를 들어 다음 명령줄은 동일합니다.

git clean -f -d -x
git clean -fdx

옵션 번들 다음에 인수가 제공되면 번들의 마지막 옵션에 적용됩니다. 다음 명령줄은 동일합니다.

myapp -a -b -c arg
myapp -abc arg

이 예제의 두 변형에서 인수 arg 는 옵션 -c에만 적용됩니다.

부울 옵션(플래그)

인수를 가진 true 옵션에 false 또는 bool가 전달되면, 예상대로 구문 분석됩니다. 그러나 인수 형식이 bool인 옵션은 일반적으로 인수를 지정할 필요가 없습니다. 부울 옵션("flags"라고도 함)은 일반적으로 항수가 0입니다System.CommandLine.ArgumentArity.ZeroOrOne. 명령줄에 옵션 이름이 있고 그 뒤에 인수가 없으면 기본값은 true입니다. 명령줄 입력에 옵션 이름이 없을 경우 값은 false로 설정됩니다. 명령이 myapp 불리언 옵션 --interactive의 값을 출력하면, 다음 입력은 다음과 같은 결과를 만듭니다.

myapp
myapp --interactive
myapp --interactive false
myapp --interactive true

False
True
False
True

버전 옵션

빌드된 System.CommandLine 앱은 루트 명령과 함께 사용되는 옵션에 대한 응답으로 --version 버전 번호를 자동으로 제공합니다. 다음은 그 예입니다.

dotnet --version

6.0.100

응답 파일

응답 파일은 명령줄 앱에 대한 토큰 집합을 포함하는 파일입니다. 응답 파일은 다음 두 가지 시나리오에서 유용한 기능 System.CommandLine 입니다.

• 터미널의 문자 제한보다 긴 입력을 지정하여 명령줄 앱을 호출합니다.
• 전체 줄을 다시 지정하지 않고 동일한 명령을 반복적으로 호출합니다.

응답 파일을 사용하려면 줄 어디에 명령, 옵션 및 인수를 삽입할지에 관계없이 파일 이름 앞에 @ 기호를 붙여 입력합니다. .rsp 파일 확장명은 일반적인 규칙이지만 파일 확장자를 사용할 수 있습니다.

다음 줄은 동일합니다.

dotnet build --no-restore --output ./build-output/
dotnet @sample1.rsp
dotnet build @sample2.rsp --output ./build-output/

sample1.rsp의 내용:

build
--no-restore
--output
./build-output/

sample2.rsp의 내용:

--no-restore

응답 파일의 텍스트를 해석하는 방법을 결정하는 구문 규칙은 다음과 같습니다.

• 토큰은 공백으로 구분됩니다. 안녕하세요!를 포함하는 줄은 두 개의 토큰인 Good과 morning!으로 처리됩니다.
• 따옴표로 묶인 여러 토큰은 단일 토큰으로 해석됩니다. "안녕하세요!"가 포함된 줄은 하나의 토큰인 안녕하세요!로 처리됩니다.
• 기호와 줄 끝 사이의 # 모든 텍스트는 주석으로 처리되고 무시됩니다.
• 접두사 @가 붙은 토큰은 추가 응답 파일을 참조할 수 있습니다.
• 응답 파일에는 여러 줄의 텍스트가 있을 수 있습니다. 줄은 연결되고 토큰 시퀀스로 해석됩니다.

지침

System.CommandLine는 형식으로 표현되는 구문 요소인 System.CommandLine.Directive을 소개합니다. [diagram] 지시자는 예입니다. 앱 이름 [diagram] 뒤를 포함하는 System.CommandLine 경우 명령줄 앱을 호출하는 대신 구문 분석 결과의 다이어그램을 표시합니다.

dotnet [diagram] build --no-restore --output ./build-output/
       ^-----^

[ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ]

지시자의 목적은 명령줄 앱 전반에 적용할 수 있는 범용 기능을 제공하는 것입니다. 지시문은 앱의 구문과 구문적으로 구별되므로 앱에 적용되는 기능을 제공할 수 있습니다.

지시문은 다음 구문 규칙을 준수해야 합니다.

• 앱 이름 뒤의 하위 명령이나 옵션 앞에 오는 명령줄의 토큰입니다.
• 대괄호로 묶입니다.
• 공백을 포함하지 않습니다.

인식할 수 없는 지시문은 구문 분석 오류를 일으키지 않고 무시됩니다.

지시문에는 지시문 이름과 콜론으로 구분된 인수가 포함될 수 있습니다.

다음 지시문이 기본 제공됩니다.

• [diagram]
• [suggest]

[diagram] 지시문

사용자와 개발자 모두 앱이 지정된 입력을 해석하는 방법을 확인하는 것이 유용할 수 있습니다. System.CommandLine 앱의 기본 기능 중 하나는 명령 입력을 해석한 결과를 미리 볼 수 있게 하는 [diagram] 지시어입니다. 다음은 그 예입니다.

myapp [diagram] --delay not-an-int --interactive --file filename.txt extra

![ myapp [ --delay !<not-an-int> ] [ --interactive <True> ] [ --file <filename.txt> ] *[ --fgcolor <White> ] ]   ???--> extra

앞의 예에서:

• 명령(myapp), 해당 자식 옵션 및 해당 옵션에 대한 인수는 대괄호를 사용하여 그룹화됩니다.
• 옵션 결과의 [ --delay !<not-an-int> ]! 경우 구문 분석 오류를 나타냅니다. not-an-int 옵션의 값 int은 예상 형식으로 변환할 수 없습니다. 오류 옵션이 포함된 명령 앞에는 !플래그가 지정됩니다: ![ myapp....
• 옵션 결과의 *[ --fgcolor <White> ]경우 명령줄에 옵션이 지정되지 않았으므로 구성된 기본값이 사용되었습니다. White 는 이 옵션의 유효 값입니다. 별표는 값이 기본값임을 나타냅니다.
• ???--> 는 앱의 명령 또는 옵션과 일치하지 않는 입력을 가리킵니다.

제안 지시문

지시 [suggest] 문을 사용하면 정확한 명령을 모르는 경우 명령을 검색할 수 있습니다.

dotnet [suggest] buil

build
build-server
msbuild

참고하십시오

• 디자인 지침
• 오픈 소스 CLI 디자인 지침
• GNU 표준
• System.CommandLine 개요
• 자습서: 시작하기 System.CommandLine