Flexible C# Command Line Parsing via Attributes

• Download demo - 3.4 MB

Introduction

Sometimes, it's still useful to drop back to the command line, especially when an application may be invoked via a script. The classes in this library provide a means of easily obtaining options from the command line, without worrying about the complexity of parsing that command line.

To use these classes, simply create a C# class with public properties for each option the user can specify and decorate each property with an attribute that describes its command line syntax.

The class library will then discover the syntax via reflection, handle any necessary type conversions, and enforce any rules about required or excluded options.

The included demo requires Visual Studio 2017 (or later) to build. The solution was originally built using Visual Studio Professional and includes a unit test project. If the unit test project causes issues, for your edition of Visual Studio, it can be safely removed.

Background

This is a common problem and there are many other packages out there that provide similar (or greater) capabilities. This particular library is designed to be lightweight, flexible, well-tested, and meets my specific requirements. I am sharing it with the community in case others have similar requirements.

Using the Code

From a consumer's perspective, these are only the three simple classes in this library:

A simple example of an option class is provided below:

using Transeric.CommandLine;
using CommandLineParserDemo.Properties;

namespace CommandLineParserDemo
{
	[CommandLineClass(typeof(Resources))]
	public class SimpleOptions
	{
		[CommandLineProperty("optionA")]
		public string OptionA { get; set; }

		[CommandLineProperty("optionB", excludes:"optionA")]
		public int OptionB { get; set; }
	}
}

This class describes a syntax where the user can specify either /optionA:ABC or /optionB:123 on a command line, but not both. The parser class automatically handles data type conversions and enforcement of the exclusion rule.

A program that uses this option class, can be as trivial as follows:

using System;
using Transeric.CommandLine;

namespace CommandLineParserDemo
{
	public class Program
	{
		public static void Main(string[] args)
		{
			var options = new SimpleOptions();
			var parser = new CommandLineParser(options);

			if (parser.Parse(args))
			{
				parser.WriteHelp(Console.Out);
				return;
			}

			Console.WriteLine(options.OptionA);
			Console.WriteLine(options.OptionB);
		}
	}
}

With this, any of the following formats would be valid for a command entered by the user:

.\CommandLineParserDemo.exe /optionA:ABC
.\CommandLineParserDemo.exe /optionA=ABC
.\CommandLineParserDemo.exe /optionA ABC
.\CommandLineParserDemo.exe /optionB:123
.\CommandLineParserDemo.exe /optionB=123
.\CommandLineParserDemo.exe /optionB 123

The following formats would not be valid. In the first case, the value "ABC" is not valid for the integer property SimpleOptions.OptionB. In the second case, the excludes parameter associated with "optionB" prevents "optionA" from also being specified.

.\CommandLineParserDemo.exe /optionB:ABC
.\CommandLineParserDemo.exe /optionA=ABC /optionB:123

While not obvious in the examples above, the parser will also automatically recognize abbreviations. The user need only provide sufficient characters, on the command line, so that the option name is unambiguous. For example, if the syntax had two different options, /alpha and /beta, the user need only specify /a and /b.

The command line arguments may not be as readily available for WinForm and WPF applications. The easiest way to get them is via the Environment.GetCommandLineArguments method or Environment.CommandLine property.

The remainder of this article provides technical detail that may exceed the needs of the average user. It may be quicker to simply play with the sample application provided with this article. The sample application is divided into three projects:

CommandLineClassAttribute Class

As mentioned earlier, the CommandLineClassAttribute is used to decorate an options class to provide the location of help resources. Its parameters are as follows:

CommandLinePropertyAttribute Class

As mentioned earlier, the CommandLinePropertyAttribute is used to decorate properties, within an option class, to provide the command line syntax of the option and to provide the location of help resources. Its parameters are as follows:

Exception Handling

There are a large number of exceptions that can be thrown by this class library. However, almost all of them are derived from one of three classes:

The full set of exceptions derived from CommandLinePropertyException are as follows:

The full set of exceptions derived from CommandLineParseException are as follows:

Points of Interest

When a value is specified as a separate argument, it cannot begin with the slash character (or CommandLineParser.OptionIndicator). By default, when the arguments are split by Windows, quotes are removed. So, it is not possible to easily distinguish between "/option" and /option. To do so, would require parsing the raw command line.

History

• 3/27/2018 - The original version was uploaded.
• 3/27/2018 - Minor typo fixes and cosmetic changes.