에서 구문 분석 및 유효성 검사를 사용자 지정하는 방법 System.CommandLine

2025-06-19

중요합니다

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

기본적으로 System.CommandLine 다음과 같은 여러 일반적인 형식을 구문 분석할 수 있는 기본 제공 파서 집합을 제공합니다.

bool
byte 및 sbyte
short 및 ushort
int 및 uint
long 및 ulong
float 및 double
decimal
DateTime 및 DateTimeOffset
DateOnly그리고 TimeOnly
Guid
FileSystemInfo, FileInfo 및 DirectoryInfo
열거형
나열된 형식의 배열 및 목록

다른 형식은 지원되지 않지만 사용자 지정 파서를 만들 수 있습니다. 구문 분석된 값의 유효성을 검사할 수도 있습니다. 이 값은 입력이 특정 조건을 충족하는지 확인하려는 경우에 유용합니다.

유효성 검사기

모든 옵션, 인수 및 명령에는 하나 이상의 유효성 검사기가 있을 수 있습니다. 유효성 검사기는 구문 분석된 값이 특정 조건을 충족하는지 확인하는 데 사용됩니다. 예를 들어 숫자가 양수이거나 문자열이 비어 있지 않은지 확인할 수 있습니다. 여러 조건을 확인하는 복잡한 유효성 검사기를 만들 수도 있습니다.

모든 기호 형식 System.CommandLine 에는 Validators 유효성 검사기 목록이 포함된 속성이 있습니다. 유효성 검사기는 입력을 구문 분석한 후에 실행되며 유효성 검사에 실패하면 오류를 보고할 수 있습니다.

사용자 지정 유효성 검사 코드를 제공하려면 다음 예제와 같이 옵션 또는 인수(또는 명령)를 호출 System.CommandLine.Option.Validators.Add 합니다.

Option<int> delayOption = new("--delay");
delayOption.Validators.Add(result =>
{
    if (result.GetValue(delayOption) < 1)
    {
        result.AddError("Must be greater than 0");
    }
});

System.CommandLine 에서는 공통 형식의 유효성을 검사하는 데 사용할 수 있는 기본 제공 유효성 검사기 집합을 제공합니다.

AcceptExistingOnly - 기존 파일 또는 디렉터리에 해당하는 값만 허용하도록 지정된 옵션 또는 인수를 구성합니다.
AcceptLegalFileNamesOnly - 유효한 파일 이름을 나타내는 값만 허용하도록 지정된 옵션 또는 인수를 구성합니다.
AcceptOnlyFromAmong - 지정된 값 집합의 값만 허용하도록 지정된 옵션 또는 인수를 구성합니다.

사용자 지정 파서

사용자 지정 파서는 복합 형식과 같은 기본 파서가 없는 형식을 구문 분석하는 데 필요합니다. 지원되는 형식을 기본 제공 파서와 다른 방식으로 구문 분석하는 데 사용할 수도 있습니다.

다음과 같은 형식이 있다고 가정합니다.Person

public class Person
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
}

값을 읽고 명령 작업에서 인스턴스 Person 를 만들 수 있습니다.

rootCommand.SetAction(parseResult =>
{
    Person person = new()
    {
        FirstName = parseResult.GetValue(firstNameOption),
        LastName = parseResult.GetValue(lastNameOption)
    };
    DoRootCommand(parseResult.GetValue(fileOption), person);
});

사용자 지정 파서에서는 기본 값을 가져오는 것과 동일한 방식으로 사용자 지정 형식을 가져올 수 있습니다.

Option<Person?> personOption = new("--person")
{
    Description = "An option whose argument is parsed as a Person",
    CustomParser = result =>
    {
        if (result.Tokens.Count != 2)
        {
            result.AddError("--person requires two arguments");
            return null;
        }
        return new Person
        {
            FirstName = result.Tokens.First().Value,
            LastName = result.Tokens.Last().Value
        };
    }
};

구문 분석하고 입력의 유효성을 검사하려면 다음 예제와 같이 대리자를 사용합니다 CustomParser .

Option<int> delayOption = new("--delay")
{
    Description = "An option whose argument is parsed as an int.",
    CustomParser = result =>
    {
        if (!result.Tokens.Any())
        {
            return 42;
        }

        if (int.TryParse(result.Tokens.Single().Value, out var delay))
        {
            if (delay < 1)
            {
                result.AddError("Must be greater than 0");
            }
            return delay;
        }
        else
        {
            result.AddError("Not an int.");
            return 0; // Ignored.
        }
    }
};

다음은 유효성 검사기를 사용해서는 할 수 없는 작업의 예시와 CustomParser을 사용해 할 수 있는 작업의 몇 가지 예입니다.

다른 종류의 입력 문자열을 구문 분석합니다(예: "1,2,3"을 int[]로 변환).
동적 입력 수(arity) 예를 들어 문자열 배열로 정의된 두 인수가 있고 명령줄 입력 System.CommandLine.Parsing.ArgumentResult.OnlyTake 에서 문자열 시퀀스를 처리해야 하는 경우 이 메서드를 사용하면 입력 문자열을 인수 간에 동적으로 나눌 수 있습니다.

다음을 통해 공유

에서 구문 분석 및 유효성 검사를 사용자 지정하는 방법 System.CommandLine

유효성 검사기

사용자 지정 파서

참고하십시오

추가 리소스