ArgsParser 5.0.0

.NET Standard 2.0
dotnet add package ArgsParser --version 5.0.0
NuGet\Install-Package ArgsParser -Version 5.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ArgsParser" Version="5.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ArgsParser --version 5.0.0
#r "nuget: ArgsParser, 5.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install ArgsParser as a Cake Addin
#addin nuget:?package=ArgsParser&version=5.0.0

// Install ArgsParser as a Cake Tool
#tool nuget:?package=ArgsParser&version=5.0.0

ArgsParser v5.0.0

Easy argument parsing for .Net applications (Core 3 or later). Full unit test coverage. Compatible with NetStandard 2.0. Available as a nuget package.


Example usage

using ArgsParser;

var indent = 2;
var parser = new Parser(args)
    .SupportsOption<int>("port", "Port to start the dev server on", 1337)
    .RequiresOption<string>("read", "Folder to read the site from", "site")
    .RequiresOption<string>("write", "Folder to write the result to")
    .SupportsFlag("serve", "Start the site going in a dev server")
    .SupportsFlag("force", "Overwrite any destination content");


if (parser.HasErrors)

var startServing = parser.IsFlagProvided("serve");
var port = parser.GetOption<int>("port");
var read = parser.GetOption<string>("read");

Custom option validators

Standard validation is concerned with the presence/absence of arguments. Custom option validators allow you to also check their contents.

For example, here's a custom validator function that checks an option contains a CSV filename. This same function can be used repeatedly for multiple options. You can also declare inline functions using lambda but this is clearer for explanatory purposes.

/// <summary>Sample validator function which checks for a CSV filename.</summary>
/// <param name="key">Name of the argument.</param>
/// <param name="value">Content passed in.</param>
/// <returns>A list of any errors.</returns>
private List<string> IsCSV(string key, object value)
    // In reality we would also need null checks etc.
    var errs = new List<string>();
    var ext = Path.GetExtension($"{value}").ToLowerInvariant();
    if (ext != ".csv") errs.Add($"{key} does not hold a CSV filename.");
    return errs;

The signature is always the same. Your validator receives an option name and value, then returns a list of zero or more error messages which will be automatically gathered alongside the standard errors. The value is an object because your options are generically typed and therefore there is no guarantee what the incoming type will be. (It's your codebase; if you know which options your validator is being registered with you can make casting assumptions.)

Once you have a validator you need to register it:

var parser = new Parser(args)
    .SupportsOption<string>("filename", "A CSV filename")
    .AddCustomOptionValidator("filename", IsCSV);

Accessing errors is described further on.

Auto-generated helper text

In the examples below, 2 is a left indent of two spaces.


These are displayed in the order they were created on the parser instance in your code.

  -port    integer       Port to start the dev server on  [1337]
  -read    text        * Folder to read the site from  [site]
  -write   text        * Folder to write the result to
  -apr     number        Annual interest  [3.596]
  -fee     number        Monthly charge  [19.50]
  -secure  true/false    Serve on HTTPS?  [True]
  -until   datetime      When to stop serving  [22/08/2023 06:28:13]
  -force                 Overwrite any destination content
  -serve                 Start the site going in a dev server

  * is required, values in square brackets are defaults
  Option missing: write
  Unknown flag: run
  -port  3000
  -read  in.txt

This doesn't directly generate output text; it returns a dictionary of key/value pairs for the provided arguments. The key is the name of the matching option or flag. The value (returned as an object) contains either null for a flag or the type-converted input for an option.

Example usage:

foreach (var item in parser.GetProvided())
    if (item.Value == null) Console.Write($" -{item.Key}");
    else Console.Write($" -{item.Key} \"{item.Value}\"");

Assuming MyApp was the name of your application, this would recreate the command used when it was called. For example:

MyApp -port "3000" -read "in.txt" -force -serve

These are returned in the order they were created on the parser instance in your code. You can easily isolate options and flags using something like .Where(x => x.Value == null).


This automatically wraps up the result of Parser.GetProvided() as a space-delimited command argument string. In other words, it provides the same output as the example of that method (minus the app name prefix).

Based on the GetProvided example, it would return:

-port "3000" -read "in.txt" -force -serve

Supported features

  • Display help showing supported flags/options
    • Also shows argument types, defaults, and optional legend
  • Display all errors
  • Display all provided input arguments
  • Required named option/values
  • Optional named option/values
  • Optional named flags
  • Default option values
  • Option types support any IConvertable, including int, bool, DateTime
  • Accepts either - or -- prefixes
  • Provides two collections of error messages
    • Expectation errors
      • Missing required options
      • Custom option validator errors
    • Argument errors
      • Option values of incorrect type
        • This may be switched to be an Expectation error in a future change
      • Unexpected values (not with an option)
      • Unknown flags or options

Example input and errors

These assume the arguments defined in the Example usage section above.

Example user input:

MyApp -run data "Site Title" --serve -ignore -port 3000

There are a few things wrong here with this input:

  • The -write option is required but not provided
  • The provided -run option is not defined
  • The "Site Title" argument has no option name preceeding it
  • The provided -ignore flag is not defined

Whilst the -read option is missing there is no error logged - it was defined with a default value of site and so the requirement is automatically met.

Errors come in two collections (the property Parser.HasErrors will be true if either has entries):

  • ExpectationErrors are where specific expectations are not met (eg a missing required option) so the relevant option/flag whose expectations are not being met is known
    • Custom option validator errors will also be in here
  • ArgumentErrors are where something was provided but there were general issues with it (eg a value provided without an option name preceeding it) so there is no certainty as to what was intended by the input given and we cannot definitively tie it to a specific option/flag

Based on the example above the errors (as key/value pairs) will be as follows:

  • ExpectationErrors keyed by the name of the related option/flag
    • writeOption missing: write
  • ArgumentErrors keyed by the 0-based offset into the arguments provided
    • 0Unknown option: run
    • 2Unexpected value: Site Title
    • 4Unknown flag: ignore

A more detailed example

(The assertions included below use NUnit. See the test project.)

var args = new string[] { "-run", "data", "Site Title", "--serve", "-ignore", "-port", "3000" };

var parser = new Parser(args)
  .SupportsOption<int>("port", "Port to start the dev server on", 1337)
  .RequiresOption<string>("read", "Folder to read the site from", "site")
  .RequiresOption<string>("write", "Folder to write the result to")
  .SupportsFlag("serve", "Start the site going in a dev server")
  .SupportsFlag("force", "Overwrite any destination content")

var result = parser.Parse();

Assert.AreEqual(4, result.ExpectationErrors.Count + result.ArgumentErrors.Count);
Assert.Contains("Option missing: write", result.ExpectationErrors.Values.ToList());
Assert.Contains("Unknown option: run", result.ArgumentErrors.Values.ToList());
Assert.Contains("Unexpected value: Site Title", result.ArgumentErrors.Values.ToList());
Assert.Contains("Unknown flag: ignore", result.ArgumentErrors.Values.ToList());

Assert.AreEqual(3000, result.GetOption<int>("port"));

Assert.AreEqual("site", result.GetOption<string>("read"));

Assert.AreEqual(null, result.GetOption<string>("write"));


Copyright K Cartlidge 2020-2023.

Licensed under GNU AGPLv3 (see here for more details). See the CHANGELOG for current status.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.0.0 92 8/27/2023
4.0.6 71 8/24/2023
4.0.5 74 8/22/2023
4.0.4 63 8/21/2023
4.0.3 58 8/21/2023
4.0.1 69 8/21/2023
4.0.0 72 8/21/2023
3.0.0 732 11/7/2020