다음을 통해 공유

System.CommandLine에 대한 명령줄 구문 개요

  • 아티클

Important

System.CommandLine은 현재 미리 보기 버전이며 이 설명서는 버전 2.0 베타 4용입니다. 일부 정보는 릴리스되기 전에 상당 부분 수정될 수 있는 시험판 제품과 관련이 있습니다. 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"

명령

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

  • dotnet run에서 run은 작업을 지정하는 명령입니다.
  • dotnet tool install에서 install는 작업을 지정하는 명령이고 tool은 관련 명령의 그룹을 지정하는 명령입니다. 다른 도구 관련 명령으로는 tool uninstall, tool list, tool update가 있습니다.

루트 명령

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

하위 명령

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

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

옵션

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

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

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

일부 Windows 명령줄 앱의 경우 옵션 이름 앞에 슬래시(/)를 사용하여 옵션을 식별합니다. 예시:

msbuild /version
        ^------^

System.CommandLine은 POSIX 및 Windows 접두사 규칙을 모두 지원합니다. 옵션을 구성할 때 접두사를 포함하여 옵션 이름을 지정합니다.

인수

인수는 옵션이나 명령에 전달되는 값입니다. 다음 예제에서는 verbosity 옵션의 인수와 build 명령의 인수를 보여 줍니다.

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

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

명시적으로 인수를 제공하지 않는 경우 인수에 기본값이 적용될 수 있습니다. 예를 들어 많은 옵션은 옵션 이름이 명령줄에 있을 때 암시적으로 기본값이 true인 부울 매개 변수입니다. 다음 명령줄 예제도 동일합니다.

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

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

일부 옵션에는 필수 인수가 있습니다. 예를 들어 .NET CLI에서 --output에는 폴더 이름 인수가 필요합니다. 인수가 제공되지 않으면 명령이 실패합니다.

인수에는 예상 형식이 있을 수 있으며 System.CommandLine은 인수를 예상 유형으로 구문 분석할 수 없는 경우 오류 메시지를 표시합니다. 예를 들어 다음 명령은 --verbosity의 유효한 값 중 하나가 “silent”가 아니므로 오류가 발생합니다.

dotnet build --verbosity silent

Cannot parse argument 'silent' for option '-v' as expected type 'Microsoft.DotNet.Cli.VerbosityOptions'. Did you mean one of the following?
Detailed
Diagnostic
Minimal
Normal
Quiet

인수에는 제공할 수 있는 값의 수에 대한 기대치도 있습니다. 인수 Arity 섹션에 예제가 나와 있습니다.

옵션 및 인수 순서

명령줄에서 인수 앞에 옵션을 제공하거나 옵션 앞에 인수를 제공할 수 있습니다. 다음 명령은 서로 동일합니다.

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은 자동 별칭을 지원하지 않습니다.

대/소문자 구분

명령 및 옵션 이름과 별칭은 기본적으로 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

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

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

Min Max 유효성 예제 예시
0 0 유효함: --file
유효하지 않음: --file a.json
유효하지 않음: --file a.json --file b.json
0 1 유효함: --flag
유효함: --flag true
유효함: --flag false
유효하지 않음: --flag false --flag false
1 1 유효함: --file a.json
유효하지 않음: --file
유효하지 않음: --file a.json --file b.json
0 n 유효함: --file
유효함: --file a.json
유효함: --file a.json --file b.json
1 n 유효함: --file a.json
유효함: --file a.json b.json
유효하지 않음: --file

System.CommandLine에는 Arity를 정의하는 ArgumentArity 구조체가 있으며 값은 다음과 같습니다.

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

Arity는 종종 형식에서 유추할 수 있습니다. 예를 들어 int 옵션의 Arity는 ExactlyOne이고, List<int> 옵션의 Arity는 OneOrMore입니다.

옵션 재정의

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

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

다중 인수

최대 Arity가 두 개 이상인 경우 System.CommandLine은 옵션 이름을 반복하지 않고 하나의 옵션에 대해 여러 인수를 허용하도록 구성할 수 있습니다.

다음 예에서 myapp 명령에 전달된 목록에는 “a”, “b”, “c”, “d”가 포함됩니다.

myapp --list a b c --list d

옵션 번들링

POSIX에서는 번들링, 즉 스태킹이라고도 하는 단일 문자 옵션을 지원할 것을 권장합니다. 번들 옵션은 단일 하이픈 접두사 뒤에 함께 지정된 단일 문자 옵션 별칭입니다. 마지막 옵션만 인수를 지정할 수 있습니다. 예를 들어 다음 명령줄은 서로 동일합니다.

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

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

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

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

부울 옵션(플래그)

인수가 bool인 옵션에 true 또는 false가 전달되면 예상대로 구문 분석됩니다. 그러나 인수 유형이 bool인 옵션은 일반적으로 인수를 지정할 필요가 없습니다. “플래그”라고도 하는 부울 옵션은 일반적으로 Arity가 ZeroOrOne입니다. 명령줄에 옵션 이름 뒤에 인수가 없는 경우 기본값은 true입니다. 명령줄 입력에 옵션 이름이 없으면 false 값이 반환됩니다. myapp 명령이 --interactive라는 부울 옵션의 값을 출력하는 경우 다음 입력은 다음과 같은 출력을 생성합니다.

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

False
True
False
True

--help 옵션

명령줄 앱은 일반적으로 사용 가능한 명령, 옵션, 인수에 대한 간략한 설명을 표시하는 옵션을 제공합니다. System.CommandLine은 도움말 출력을 자동으로 생성합니다. 예시:

dotnet list --help

Description:
  List references or packages of a .NET project.

Usage:
  dotnet [options] list [<PROJECT | SOLUTION>] [command]

Arguments:
  <PROJECT | SOLUTION>  The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -?, -h, --help  Show command line help.

Commands:
  package    List all package references of the project or solution.
  reference  List all project-to-project references of the project.

앱 사용자는 플랫폼마다 다른 도움말 요청 방식에 익숙할 수 있으므로 System.CommandLine에 빌드된 앱은 다양한 도움말 요청 방식에 응답합니다. 다음 명령은 모두 동일합니다.

dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?

도움말 출력에 사용 가능한 모든 명령, 인수, 옵션이 반드시 표시되는 것은 아닙니다. 이 중 일부는 숨겨져 있어서 도움말 출력에는 표시되지 않지만 명령줄에서 지정할 수 있습니다.

--version 옵션

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!을 포함하는 줄은 두 개의 토큰인 Good과 morning!으로 처리됩니다.
  • 따옴표로 묶인 여러 토큰은 단일 토큰으로 해석됩니다. “Good morning!”은 Good morning!이라는 하나의 토큰으로 처리됩니다.
  • # 기호와 줄 끝 사이의 모든 텍스트는 주석으로 처리되고 무시됩니다.
  • @ 접두사가 붙은 토큰은 추가 응답 파일을 참조할 수 있습니다.
  • 응답 파일에는 여러 줄의 텍스트가 있을 수 있습니다. 줄은 연결되고 토큰 시퀀스로 해석됩니다.

지시문

System.CommandLine은 지시문이라는 구문 요소를 도입합니다. [parse] 지시문은 예제입니다. 앱 이름 뒤에 [parse]를 포함하면 System.CommandLine은 명령줄 앱을 호출하는 대신 구문 분석 결과의 다이어그램을 표시합니다.

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

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

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

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

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

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

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

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

[parse] 지시문

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

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

[suggest] 지시문

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

dotnet [suggest] buil

build
build-server
msbuild

디자인 지침

다음 섹션에서는 CLI를 설계하는 경우 준수를 권장하는 지침을 제시합니다. 앱이 명령줄에서 기대하는 것을 REST API 서버가 URL에서 기대하는 것과 유사하다고 생각하세요. REST API에 대한 일관된 규칙을 통해 클라이언트 앱 개발자는 이를 쉽게 사용할 수 있습니다. 마찬가지로 명령줄 앱의 사용자도 CLI 디자인이 일반적인 패턴을 따르는 경우 더 나은 경험을 할 수 있습니다.

일단 CLI를 생성하면 변경하기가 어렵습니다. 특히 사용자가 계속 실행되기를 기대하는 스크립트에서 CLI를 사용한 경우에는 더욱 그렇습니다. 이 지침은 .NET CLI를 따라 개발되었기 때문에 항상 이 지침을 따르는 것은 아닙니다. 호환성이 손상되는 변경을 도입하지 않고도 이를 수행할 수 있는 .NET CLI를 업데이트하고 있습니다. 이 작업의 예로 .NET 7의 dotnet new에 대한 새로운 설계를 들 수 있습니다.

명령 및 하위 명령

명령에 하위 명령이 있는 경우 명령은 작업을 지정하기보다는 영역 또는 하위 명령의 그룹화 식별자 역할을 해야 합니다. 앱을 호출할 때 그룹화 명령과 그 하위 명령 중 하나를 지정합니다. 예를 들어 dotnet tool을 실행하려고 하면 tool 명령이 install 및 list와 같은 도구 관련 하위 명령 그룹만 식별하기 때문에 오류 메시지가 표시됩니다. dotnet tool install을 실행할 수 있지만 dotnet tool을 단독으로 실행하면 불완전합니다.

영역을 정의하는 것이 사용자에게 도움이 되는 방법 중 하나는 도움말 출력을 정리하는 것입니다.

CLI 내에는 암시적 영역이 있는 경우가 많습니다. 예를 들어 .NET CLI에서 암시적 영역은 프로젝트이고 Docker CLI에서는 이미지입니다. 따라서 영역을 포함하지 않고 dotnet build를 사용할 수 있습니다. CLI에 암시적 영역이 있는지 고려합니다. 암시적 영역이 있다면 docker build 및 docker image build에서와 같이 사용자가 선택적으로 포함하거나 생략할 수 있도록 허용할지 고려합니다. 사용자가 암시적 영역을 선택적으로 입력하도록 허용하면 이 명령 그룹에 대한 도움말 및 탭 완성 기능도 자동으로 제공됩니다. 동일한 작업을 수행하는 두 개의 명령을 정의하여 암시적 그룹을 선택적으로 사용할 수 있도록 합니다.

매개 변수로서의 옵션

옵션은 동작 자체를 지정하는 것이 아니라 명령에 매개 변수를 제공해야 합니다. 항상 System.CommandLine(--help는 도움말 정보를 표시함)이 따르는 것은 아니지만 권장되는 설계 원칙입니다.

짧은 형식 별칭

일반적으로 정의하는 짧은 형식 옵션 별칭의 수를 최소화하는 것이 좋습니다.

특히 다음 별칭은 .NET CLI 및 기타 .NET 명령줄 앱에서 일반적인 사용법과 다르게 사용하지 마세요.

  • --interactive에 대한 -i.

    이 옵션은 사용자에게 명령에 대한 답변이 필요한 질문에 대한 입력 메시지가 표시될 수 있음을 알려줍니다. 예를 들어 사용자 이름을 묻는 메시지가 표시됩니다. CLI는 스크립트에서 사용될 수 있으므로 이 스위치를 지정하지 않은 사용자에게 메시지를 표시할 때는 주의해야 합니다.

  • --output에 대한 -o.

    일부 명령은 실행 결과로 파일을 생성합니다. 이 옵션을 사용하면 해당 파일의 위치를 결정하는 데 도움이 됩니다. 단일 파일이 만들어지는 경우 이 옵션은 파일 경로여야 합니다. 파일이 많이 만들어지는 경우 이 옵션은 디렉터리 경로여야 합니다.

  • --verbosity에 대한 -v.

    명령은 종종 콘솔에서 사용자에게 출력을 제공하는데, 이 옵션은 사용자가 요청하는 출력의 양을 지정하는 데 사용됩니다. 자세한 내용은 이 문서 뒷부분의 --verbosity 옵션을 참조하세요.

또한 .NET CLI로 사용이 제한된 일부 별칭도 있습니다. 이러한 별칭을 앱의 다른 옵션에 사용할 수 있지만 혼동할 수 있다는 점에 유의하세요.

  • --configuration의 경우 -c

    이 옵션은 Debug 또는 Release와 같이 명명된 빌드 구성을 참조하는 경우가 많습니다. 구성에 원하는 이름을 사용할 수 있지만 대부분의 도구는 이러한 이름 중 하나를 예상합니다. 이 설정은 Debug 구성을 빌드할 때 코드 최적화를 덜 수행하는 등 해당 구성에 적합한 방식으로 다른 속성을 구성하는 데 자주 사용됩니다. 명령의 작동 모드가 다른 경우 이 옵션을 고려합니다.

  • --framework의 경우 -f

    이 옵션은 실행할 단일 TFM(대상 프레임워크 모니커)을 선택하는 데 사용되므로 선택한 TFM에 따라 CLI 애플리케이션의 동작이 달라지는 경우 이 플래그를 지원해야 합니다.

  • --property의 경우 -p

    애플리케이션이 결국 MSBuild를 호출하는 경우 사용자는 어떤 식으로든 해당 호출을 사용자 지정해야 하는 경우가 많습니다. 이 옵션을 사용하면 명령줄에서 MSBuild 속성을 제공하고 기본 MSBuild 호출에 전달할 수 있습니다. 앱에서 MSBuild를 사용하지 않지만 키-값 쌍 집합이 필요한 경우 사용자의 기대치를 활용하기 위해 동일한 옵션 이름을 사용하는 것이 좋습니다.

  • --runtime의 경우 -r

    애플리케이션이 다른 런타임에서 실행될 수 있거나 런타임별 로직이 있는 경우 런타임 식별자를 지정하는 방법으로 이 옵션을 지원하는 것을 고려하세요. 앱에서 --runtime을 지원하는 경우 --os 및 --arch도 지원하는 것이 좋습니다. 이러한 옵션을 사용하면 RID의 OS 또는 아키텍처 부분만 지정하고 지정하지 않은 부분은 현재 플랫폼에서 결정하도록 남겨둘 수 있습니다. 자세한 내용은 dotnet publish를 참조하세요.

짧은 이름

명령, 옵션, 인수의 이름은 가능한 한 짧고 철자법이 쉽도록 만드세요. 예를 들어 class가 충분히 명확하다면 classification 명령을 만들지 마세요.

소문자 이름

대문자 별칭을 만들어 명령이나 옵션의 대소문자를 구분할 수 있는 경우를 제외하고는 소문자로만 이름을 정의하세요.

Kebab 대/소문자 이름

Kebab 대소문자를 사용하여 단어를 구분합니다. 예들 들어 --additional-probing-path입니다.

복수화

앱 내에서는 복수형을 일관성 있게 사용하세요. 예를 들어 여러 값을 가질 수 있는 옵션의 경우 복수형과 단수형 이름을 혼용하지 마세요(최대 Arity가 1보다 큼).

옵션 이름 일관성
--additional-probing-paths 및 --sources ✔️
--additional-probing-path 및 --source ✔️
--additional-probing-paths 및 --source ❌
--additional-probing-path 및 --sources ❌

동사 및 명사

작업을 참조하는 명령(아래에 하위 명령이 없는 명령)에는 명사 대신 동사를 사용합니다. 예를 들면 dotnet workload removal가 아니라 dotnet workload remove을 사용합니다. 그리고 옵션에 동사 대신 명사를 사용합니다. 예를 들면 --configure가 아니라 --configuration을 사용합니다.

--verbosity 옵션

System.CommandLine 애플리케이션은 일반적으로 콘솔로 전송되는 출력의 양을 지정하는 --verbosity 옵션을 제공합니다. 다음은 표준 5가지 설정입니다.

  • Q[uiet]
  • M[inimal]
  • N[ormal]
  • D[etailed]
  • Diag[nostic]

이것이 표준 이름이지만 기존 앱에서는 Quiet 대신 Silent, Diagnostic 대신 Trace, Debug 또는 Verbose를 사용하기도 합니다.

각 앱은 각 수준에 표시되는 항목을 결정하는 자체 기준을 정의합니다. 일반적으로 앱에는 다음 세 가지 수준만 필요합니다.

  • Quiet
  • 일반
  • 진단

앱에 5가지 수준이 필요하지 않은 경우에도 옵션에서 동일한 5가지 설정을 정의해야 합니다. 이 경우 Minimal과 Normal은 동일한 출력을 생성하고 Detailed와 Diagnostic도 마찬가지로 동일한 출력을 생성합니다. 이렇게 하면 사용자가 익숙한 것을 입력하기만 하면 가장 적합한 것을 사용할 수 있습니다.

Quiet에 대한 예상은 콘솔에 출력이 표시되지 않는 것입니다. 그러나 앱에서 대화형 모드를 제공하는 경우 앱은 다음 대안 중 하나를 수행해야 합니다.

  • --verbosity가 Quiet인 경우에도 --interactive가 지정되었으면 입력 프롬프트를 표시합니다.
  • --verbosity Quiet와 --interactive를 함께 사용하지 않도록 합니다.

그렇지 않으면 앱은 사용자에게 대기 중임을 알리지 않고 입력을 기다립니다. 애플리케이션이 멈춘 것처럼 표시되며 사용자는 애플리케이션이 입력을 기다리고 있다는 사실을 알 수 없습니다.

별칭을 정의하는 경우 --verbosity에 -v를 사용하고 인수가 없는 -v를 --verbosity Diagnostic의 별칭으로 만듭니다. --verbosity Quiet에 -q를 사용합니다.

.NET CLI 및 POSIX 규칙

.NET CLI는 모든 POSIX 규칙을 일관되게 따르지 않습니다.

이중 대시

.NET CLI의 여러 명령에는 이중 대시 토큰이 특수하게 구현되어 있습니다. dotnet run, dotnet watch, dotnet tool run의 경우 -- 다음에 오는 토큰은 명령이 실행 중인 앱으로 전달됩니다. 예시:

dotnet run --project ./myapp.csproj -- --message "Hello world!"
                                    ^^

이 예에서는 --project 옵션이 dotnet run 명령에 전달되고 인수가 포함된 --message 옵션이 실행될 때 myapp에 명령줄 옵션으로 전달됩니다.

dotnet run를 사용하여 실행하는 앱에 옵션을 전달할 때 -- 토큰이 항상 필요한 것은 아닙니다. 이중 대시가 없으면 dotnet run 명령은 dotnet run 자체 또는 MSBuild에 적용되는 것으로 인식되지 않는 모든 옵션을 실행 중인 앱에 자동으로 전달합니다. 따라서 dotnet run이 인수와 옵션을 인식하지 못하므로 다음 명령줄은 동일합니다.

dotnet run -- quotes read --delay 0 --fg-color red
dotnet run quotes read --delay 0 --fg-color red

옵션-인수 구분 기호 생략

.NET CLI는 한 문자 옵션 별칭을 지정할 때 구분 기호를 생략할 수 있는 POSIX 규칙을 지원하지 않습니다.

옵션 이름을 반복하지 않고 여러 인수 사용

.NET CLI는 옵션 이름을 반복하지 않고는 하나의 옵션에 대해 여러 인수를 허용하지 않습니다.

부울 옵션

NET CLI에서 일부 부울 옵션은 false을 전달할 때 true을 전달할 때와 동일한 동작을 초래합니다. 이 동작은 옵션을 구현하는 .NET CLI 코드가 값을 무시하고 옵션의 존재 여부만 확인할 때 발생합니다. 예를 들어 dotnet build 명령의 경우 --no-restore입니다. no-restore false을 전달하면 no-restore true 또는 no-restore을 지정할 때와 동일하게 복원 작업을 건너뛰게 됩니다.

Kebab 대/소문자

경우에 따라 .NET CLI는 명령, 옵션 또는 인수 이름에 Kebab 대/소문자를 사용하지 않는 경우가 있습니다. 예를 들어 --additional-probing-path 대신 --additionalprobingpath이라는 이름의 .NET CLI 옵션이 있습니다.

참고 항목