System.Commandline 라이브러리로 빌드된 앱에서 도움말을 사용자 지정하는 방법
특정 명령, 옵션 또는 인수에 대한 도움말을 사용자 지정할 수 있으며 전체 도움말 섹션을 추가하거나 바꿀 수 있습니다.
이 문서의 예에서는 다음 명령줄 애플리케이션에서 작동합니다.
이 코드에는 using 지시문이 필요합니다.
using System.CommandLine;
var fileOption = new Option<FileInfo>(
"--file",
description: "The file to print out.",
getDefaultValue: () => new FileInfo("scl.runtimeconfig.json"));
var lightModeOption = new Option<bool> (
"--light-mode",
description: "Determines whether the background color will be black or white");
var foregroundColorOption = new Option<ConsoleColor>(
"--color",
description: "Specifies the foreground color of console output",
getDefaultValue: () => ConsoleColor.White);
var rootCommand = new RootCommand("Read a file")
{
fileOption,
lightModeOption,
foregroundColorOption
};
rootCommand.SetHandler((file, lightMode, color) =>
{
Console.BackgroundColor = lightMode ? ConsoleColor.White: ConsoleColor.Black;
Console.ForegroundColor = color;
Console.WriteLine($"--file = {file?.FullName}");
Console.WriteLine($"File contents:\n{file?.OpenText().ReadToEnd()}");
},
fileOption,
lightModeOption,
foregroundColorOption);
await rootCommand.InvokeAsync(args);
사용자 지정하지 않으면 다음 도움말 출력이 생성됩니다.
Description:
Read a file
Usage:
scl [options]
Options:
--file <file> The file to print out. [default: scl.runtimeconfig.json]
--light-mode Determines whether the background color will be black or
white
--color Specifies the foreground color of console output
<Black|Blue|Cyan|DarkBlue|DarkCyan|DarkGray|DarkGreen|Dark [default: White]
Magenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|White|Ye
llow>
--version Show version information
-?, -h, --help Show help and usage information
단일 옵션 또는 인수에 대한 도움말 사용자 지정
Important
System.CommandLine은 현재 미리 보기 버전이며 이 설명서는 버전 2.0 베타 4용입니다.
일부 정보는 릴리스되기 전에 상당 부분 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다.
옵션 인수 이름을 사용자 지정하려면 옵션의 ArgumentHelpName 속성을 사용합니다. 그리고 HelpBuilder.CustomizeSymbol을 사용하면 명령, 옵션 또는 인수에 대한 도움말 출력의 여러 부분을 사용자 지정할 수 있습니다(Symbol은 세 가지 형식 모두의 기본 클래스임). CustomizeSymbol을 사용하면 다음을 지정할 수 있습니다.
- 첫 번째 열 텍스트입니다.
- 두 번째 열 텍스트입니다.
- 기본값이 설명되는 방식입니다.
샘플 앱에서는 --light-mode에 대해 적절하게 설명되어 있지만 --file 및 --color 옵션 설명을 변경하면 도움이 될 것입니다. --file의 경우 인수는 <file> 대신 <FILEPATH>로 식별될 수 있습니다. --color 옵션의 경우 열 1에서 사용 가능한 색 목록을 줄일 수 있으며, 열 2에서는 일부 색이 일부 백그라운드에서 작동하지 않는다는 경고를 추가할 수 있습니다.
이러한 변경을 수행하려면 이전 코드에 표시된 await rootCommand.InvokeAsync(args); 줄을 삭제하고 그 자리에 다음 코드를 추가합니다.
fileOption.ArgumentHelpName = "FILEPATH";
var parser = new CommandLineBuilder(rootCommand)
.UseDefaults()
.UseHelp(ctx =>
{
ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
firstColumnText: "--color <Black, White, Red, or Yellow>",
secondColumnText: "Specifies the foreground color. " +
"Choose a color that provides enough contrast " +
"with the background color. " +
"For example, a yellow foreground can't be read " +
"against a light mode background.");
})
.Build();
parser.Invoke(args);
업데이트된 코드에는 추가 using 지시문이 필요합니다.
using System.CommandLine.Builder;
using System.CommandLine.Help;
using System.CommandLine.Parsing;
이제 앱은 다음과 같은 도움말 출력을 생성합니다.
Description:
Read a file
Usage:
scl [options]
Options:
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
--light-mode Determines whether the background color will be black or white
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
with the background color. For example, a yellow foreground can't be read
against a light mode background.
--version Show version information
-?, -h, --help Show help and usage information
이 출력은 firstColumnText 및 secondColumnText 매개 변수가 해당 열 내에서 단어 줄 바꿈을 지원함을 보여 줍니다.
도움말 섹션 추가 또는 바꾸기
도움말 출력의 전체 섹션을 추가하거나 바꿀 수 있습니다. 예를 들어, Spectre.Console NuGet 패키지를 사용하여 설명 섹션에 일부 ASCII 아트를 추가한다고 가정해 보겠습니다.
UseHelp 메서드에 전달된 람다에서 HelpBuilder.CustomizeLayout에 대한 호출을 추가하여 레이아웃을 변경합니다.
fileOption.ArgumentHelpName = "FILEPATH";
var parser = new CommandLineBuilder(rootCommand)
.UseDefaults()
.UseHelp(ctx =>
{
ctx.HelpBuilder.CustomizeSymbol(foregroundColorOption,
firstColumnText: "--color <Black, White, Red, or Yellow>",
secondColumnText: "Specifies the foreground color. " +
"Choose a color that provides enough contrast " +
"with the background color. " +
"For example, a yellow foreground can't be read " +
"against a light mode background.");
ctx.HelpBuilder.CustomizeLayout(
_ =>
HelpBuilder.Default
.GetLayout()
.Skip(1) // Skip the default command description section.
.Prepend(
_ => Spectre.Console.AnsiConsole.Write(
new FigletText(rootCommand.Description!))
));
})
.Build();
await parser.InvokeAsync(args);
앞의 코드에는 추가 using 지시문이 필요합니다.
using Spectre.Console;
System.CommandLine.Help.HelpBuilder.Default 클래스를 사용하면 기존 도움말 서식 지정 기능을 재사용하고 이를 사용자 지정 도움말로 구성할 수 있습니다.
이제 도움말 출력은 다음과 같습니다.
____ _ __ _ _
| _ \ ___ __ _ __| | __ _ / _| (_) | | ___
| |_) | / _ \ / _` | / _` | / _` | | |_ | | | | / _ \
| _ < | __/ | (_| | | (_| | | (_| | | _| | | | | | __/
|_| \_\ \___| \__,_| \__,_| \__,_| |_| |_| |_| \___|
Usage:
scl [options]
Options:
--file <FILEPATH> The file to print out. [default: CustomHelp.runtimeconfig.json]
--light-mode Determines whether the background color will be black or white
--color <Black, White, Red, or Yellow> Specifies the foreground color. Choose a color that provides enough contrast
with the background color. For example, a yellow foreground can't be read
against a light mode background.
--version Show version information
-?, -h, --help Show help and usage information
Spectre.Console로 서식을 지정하는 대신 문자열을 대체 섹션 텍스트로 사용하려면 이전 예의 Prepend 코드를 다음 코드로 바꿉니다.
.Prepend(
_ => _.Output.WriteLine("**New command description section**")
참고 항목
.NET