Arguments, input and exit codes

The arguments of a program

The shell splits a command line at spaces, and the runtime passes the words after the program name to Main and to the args of a top-level program. The array is never null: a program started with no arguments gets an empty array.

Console.WriteLine($"arguments: {args.Length}"); for (var i = 0; i < args.Length; i++) { Console.WriteLine($"{i}: {args[i]}"); }

Passing them through dotnet run

dotnet run has options of its own, so its own arguments and the arguments of the program are separated by --. Everything after it goes to the program:

dotnet run -- alpha beta

arguments: 2
0: alpha
1: beta

Without the separator, ---less words may be taken for options of dotnet run itself, and an unknown one stops the command before the program starts. A published program needs no separator: ./tool alpha beta passes both words straight to Main.

An argument that contains a space is quoted by the shell, which removes the quotes again:

dotnet run -- "Ada Lovelace" 1843

arguments: 2
0: Ada Lovelace
1: 1843

Reading standard input

Console.ReadLine reads one line without its line break, and returns null at the end of the input. Console.Write is WriteLine without the line break, which is how a prompt stays on the same line as the answer.

Console.Write("name: "); var name = Console.ReadLine(); Console.WriteLine($"hello, {name}");

printf 'Ada\n' | dotnet run

name: hello, Ada

The prompt and the answer share a line because the prompt has no line break. A run with no input at all gets null from ReadLine and prints hello, , which is why a real program checks for it:

var line = Console.ReadLine(); if (line is null) { Console.Error.WriteLine("no input"); return 1; } Console.WriteLine(line.Length); return 0;

dotnet run < /dev/null
echo "status: $?"

no input
status: 1

The last return 0; is not decoration. A return with a value turns the generated entry point into an int method, and from then on every path must return: without the last line the build stops with

Program.cs(1,1): error CS0161: '<top-level-statements-entry-point>': not all code paths return a value

A program that is shorter than this one sets Environment.ExitCode instead and returns nothing, which the next section shows.

Console.Error writes to standard error, which a shell can redirect apart from standard output. A message about a failure belongs there, and the normal output belongs on Console.Out.

A usage message and an exit status

A command-line tool says what it wants when it is called wrongly, and it says it with a non-zero status so a script can tell. The classic program with an int Main is the shortest way:

class Program { static int Main(string[] args) { if (args.Length == 0) { Console.Error.WriteLine("usage: tool <name>"); return 2; } Console.WriteLine($"hello, {args[0]}"); return 0; } }

dotnet run
echo "status: $?"

usage: tool <name>
status: 2

Two is the usual status for "wrong usage" and one for "it ran and failed"; zero is success. The number is a convention of the operating system, and nothing in C# enforces it.

ExitCode against Exit

A top-level program returns nothing, so it sets the status instead:

Console.WriteLine("work done"); Environment.ExitCode = 3;

dotnet run
echo "status: $?"

work done
status: 3

Environment.ExitCode is read when the entry point returns, so the program runs to its end. Environment.Exit stops it at once: no finally block runs and nothing is disposed. A program that has to flush a file therefore sets ExitCode or returns from Main instead of calling Exit.

Exercises

  1. Run the first program with no arguments and with three, and compare the output of args.Length.
  2. Pass "Ada Lovelace" without quotes and then with them. What does the program print in each case?
  3. Replace return 2 in the third program with Environment.Exit(2) and add a finally that prints. Which line appears?
  4. Feed the input program a file with three lines. How many lines does it read, and what does the fourth call return?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does args hold?

    Answer

    The words after the program name, split by the shell

    The runtime passes the arguments without the program name, and a program started with none gets an empty array.

  2. Why does dotnet run -- alpha beta need the double dash?

    Answer

    Everything after it goes to the program, not to dotnet run

    dotnet run has options of its own, and -- separates them from the arguments of the program.

  3. What does this program print with no arguments? Console.WriteLine(args.Length); Console.WriteLine(args.Length == 0 ? "none" : args[0]);

    Answer

    0 / none

    args is an empty array rather than null, so its length is 0 and the conditional expression picks none.

  4. What does Console.ReadLine return at the end of the input?

    Answer

    null

    ReadLine returns null when no more characters are available, and an empty line gives an empty string instead.

  5. What does this program print, and with which exit status? class Program { static int Main(string[] args) { Console.Error.WriteLine("usage: tool"); return 2; } }

    Answer

    usage: tool / exit status: 2

    The line goes to standard error rather than standard output, and the value Main returns becomes the exit status.

  6. What does this program print? Console.Write("a"); Console.Write("b"); Console.WriteLine("c");

    Answer

    abc

    Write adds no line break, so the three calls share one line and WriteLine ends it.

  7. What is the difference between Environment.ExitCode and Environment.Exit?

    Answer

    ExitCode sets the status the program will leave; Exit ends the program at once

    ExitCode is read when Main returns, so the program finishes; Exit terminates immediately and skips finally blocks.

  8. What does this program print? Console.WriteLine("3"); Environment.ExitCode = 3;

    Answer

    3, then exit status 3

    The line prints the character 3, and the property makes the process leave the status 3.

  9. Which status does a shell read as success?

    Answer

    0

    Zero is success by convention, and any other number lets a script treat the run as a failure.

  10. What does this program print when the shell passes Ada? if (args.Length > 0) { Console.WriteLine($"hi {args[0]}"); }

    Answer

    hi Ada

    args[0] is the first word after the program name, so the interpolated string holds Ada.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev