디자인 지침

다음 섹션에서는 저희가 권장하는 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 명령줄 앱에서 일반적인 사용과 다르게 다음 별칭을 사용하지 않도록 합니다.

• -i 을 선택합니다 --interactive.

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

• -o 을 선택합니다 --output.

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

• -v 을 선택합니다 --verbosity.

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

일반적인 사용량이 .NET CLI로 제한되는 일부 별칭도 있습니다. 이러한 별칭을 앱의 다른 옵션에 사용할 수 있지만 혼동의 가능성을 알고 있어야 합니다.

• -c에 대한 --configuration

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

• -f에 대한 --framework

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

• -p에 대한 --property

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

• -r에 대한 --runtime

  애플리케이션이 다른 런타임에서 실행되거나 런타임 관련 논리가 있는 경우 런타임 식별자를 지정하는 방법으로 이 옵션을 지원하는 것이 좋습니다. 앱이 --runtime를 지원하는 경우, --os와 --arch도 지원하는 것을 고려하십시오. 이러한 옵션을 사용하면 RID의 OS 또는 아키텍처 부분만 지정할 수 있으며, 지정되지 않은 부분은 현재 플랫폼을 기준으로 자동으로 결정됩니다. 자세한 내용은 dotnet publish를 참조하세요.

짧은 이름

명령, 옵션 및 인수의 이름을 최대한 짧고 쉽게 철자할 수 있도록 합니다. 예를 들어 충분히 명확한 경우 class 명령을 classification만들지 마세요.

이름을 소문자로 표기

소문자만으로 이름을 정의하십시오. 명령이나 옵션을 대/소문자를 구분하지 않도록 하기 위해 대문자 별칭을 만들 수 있습니다.

케밥 케이스 이름

케밥 케이스를 사용하여 단어를 구분합니다. 예: --additional-probing-path.

복수화

앱 내에서 복수화에서 일관성을 유지합니다. 예를 들어 여러 값을 가질 수 있는 옵션에 복수 및 단수 이름을 혼합하지 마세요(최대 크기가 1보다 큼).

동사 및 명사

명령어 중 하위 명령이 없는 동작을 참조하는 경우에는 명사가 아니라 동사를 사용합니다. 예를 들면: dotnet workload remove, dotnet workload removal. 그리고 옵션에는 동사가 아니라 명사를 사용해야 합니다. 예를 들어: --configuration, --configure이 아닙니다.

옵션 --verbosity

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

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

이들은 표준 이름이지만, 기존 앱은 때때로 Silent를 Quiet 대신 사용하고, Trace, Debug, 또는 Verbose를 Diagnostic 대신 사용합니다.

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

• 조용한
• 정상
• 진단

앱에 5개의 다른 수준이 필요하지 않은 경우 이 옵션은 여전히 동일한 5개의 설정을 정의해야 합니다. 이 경우 MinimalNormal 동일한 출력을 생성하며 DetailedDiagnostic 마찬가지로 동일합니다. 이렇게 하면 사용자가 익숙한 내용을 입력할 수 있으며 가장 적합한 항목이 사용됩니다.

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

• --interactive이 지정되면 --verbosity이 Quiet인 경우에도 입력 프롬프트를 표시합니다.
• 함께 사용하는 --verbosity Quiet--interactive 것을 허용하지 않습니다.

그렇지 않으면 앱은 대기 중인 내용을 사용자에게 알리지 않고 입력을 기다립니다. 애플리케이션이 중지된 것으로 나타나고 사용자는 애플리케이션이 입력을 기다리고 있다는 사실을 전혀 알지 못합니다.

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

.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 코드가 값을 무시하고 옵션의 존재 여부만 확인하는 경우 발생합니다. --no-restore은/는 dotnet build 명령에 대한 예입니다. --no-restore false를 전달하면 --no-restore true 또는 --no-restore를 지정한 경우와 동일하게 복원 작업이 건너뜁니다.

케밥 케이스

경우에 따라 .NET CLI에서는 명령어, 옵션 또는 인수 이름에 케밥 표기법을 사용하지 않습니다. 예를 들어, --additionalprobingpath 대신 --additional-probing-path로 이름이 지정된 .NET CLI 옵션이 있습니다.

참고하십시오

• 오픈 소스 CLI 디자인 지침
• GNU 표준