Console input, output, arguments and exit codes

The same eight lines of C# printed the total 1,234,567.50 as 1,234,567.50 under the culture of the United States, 12,34,567.50 under India’s and 1.234.567,50 under Germany’s, and read the price 2.50 as 250 under the last. A console program has more to get right than its arithmetic: where its input ends, what to do with a line that is not a number, where its errors go, what its exit code tells the script that ran it, and which cultureculture: The conventions of a language and region, such as en-IN or de-DE, that .NET uses to format and parse numbers, dates and money. CultureInfo.CurrentCulture follows the settings of the computer. shapes every number it reads and writes.

This lesson builds a small marks tool step by step: a loop that stops when the input ends, parsing that turns bad text into a decision instead of a crash, results and problems on separate streams, numbers in the invariant culture, and arguments checked before any work starts.

Standard input ends when ReadLine returns null

A program reads its standard inputstandard input: The stream a program reads its input from. It is the keyboard by default, and a shell can connect it to a file with < or to another program's output with |; Console.ReadLine reads it line by line. without knowing where it comes from: the keyboard, a file after < on the command line, or another program after |. Console.ReadLine() returns the next line without its line ending, and once no lines are left, it returns null. That is why its type is string?. This program adds up the marks it reads, one per line, until the input ends:

// Adds up the marks on standard input, one per line, until the input ends.
int count = 0;
int total = 0;
string? line;
while ((line = Console.ReadLine()) is not null)
{
    if (string.IsNullOrWhiteSpace(line))
    {
        continue; // a blank line holds no mark
    }
    total += int.Parse(line);
    count++;
}
Console.WriteLine($"{count} marks, total {total}");

72
85

90

3 marks, total 247

The input had four lines, and the program counted 3 marks with a total of 247. The while condition reads and tests in one go: the assignment puts the next line into line, and the comparison with null ends the loop where the input ends. A blank line is not the end of the input: ReadLine returns "", an empty string, so the program skips it with string.IsNullOrWhiteSpace. Step through the run:

Reading a fixed number of lines is the mistake this loop avoids. This program expects three marks and gets two:

// Expects exactly three marks on standard input, and gets two.
int total = 0;
for (int i = 0; i < 3; i++)
{
    string? line = Console.ReadLine();
    total += int.Parse(line!); // the ! hides that line is null once the input has ended
}
Console.WriteLine($"Total: {total}");

72
85

Unhandled exception. System.ArgumentNullException: Value cannot be null. (Parameter 's')
   at System.Int32.Parse(String s)
   at Program.<Main>$(String[] args) in ./three.cs:line 6

The third ReadLine returned null, and int.Parse stopped the program with an ArgumentNullException at line 6, exit status 134. The ! after line had told the compiler not to warn about exactly that, as the previous lesson showed.

TryParse turns bad text into a decision

int.Parse in total.cs trusts its input: a line such as 9O, typed with the letter O, would stop the program with a FormatException. int.TryParse takes the same text and answers with a bool instead: true and the number, or false when the text is not one, as Microsoft’s guide to parsing numbers describes. This program tries both on eight pieces of text:

using System.Globalization;

// What int.Parse and int.TryParse make of eight pieces of text.
string[] inputs = ["42", " 42 ", "-7", "4 2", "", "9O", "3000000000", "1,250"];
Console.WriteLine($"{"Text",-14} {"int.Parse",-18} int.TryParse");
foreach (string text in inputs)
{
    string parsed;
    try
    {
        parsed = int.Parse(text, CultureInfo.InvariantCulture).ToString(CultureInfo.InvariantCulture);
    }
    catch (Exception e) when (e is FormatException or OverflowException)
    {
        parsed = e.GetType().Name;
    }
    bool ok = int.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out int value);
    string tried = $"{ok}, {value.ToString(CultureInfo.InvariantCulture)}";
    string shown = $"\"{text}\"";
    Console.WriteLine($"{shown,-14} {parsed,-18} {tried}");
}
bool grouped = int.TryParse("1,250", NumberStyles.AllowThousands, CultureInfo.InvariantCulture, out int withGroups);
Console.WriteLine($"With NumberStyles.AllowThousands, \"1,250\" gives {grouped}, {withGroups.ToString(CultureInfo.InvariantCulture)}");

Text           int.Parse          int.TryParse
"42"           42                 True, 42
" 42 "         42                 True, 42
"-7"           -7                 True, -7
"4 2"          FormatException    False, 0
""             FormatException    False, 0
"9O"           FormatException    False, 0
"3000000000"   OverflowException  False, 0
"1,250"        FormatException    False, 0
With NumberStyles.AllowThousands, "1,250" gives True, 1250

Each row follows from the rules of the default style for integers, NumberStyles.Integer, which allows digits, white space before and after, and a sign in front. So " 42 " and "-7" parse, while "4 2", "" and "9O" throw a FormatException. "3000000000" is a well-formed number that does not fit: an int holds at most 2,147,483,647, so it throws an OverflowException instead. "1,250" fails because a group separator is not allowed until you add NumberStyles.AllowThousands, as the last line shows. In every failing row TryParse returned false and set its out variable to 0, the False, 0 of the last column, so the program could decide what to do next instead of crashing.

The second argument of each call, CultureInfo.InvariantCulture, decides which characters count as the decimal and group separators. Without it, parsing uses the culture of the computer, and a later section shows what that costs.

Results go to standard output, problems to standard error

A program has two output streams. Standard outputstandard output: The stream where a program writes its results, with Console.Write and Console.WriteLine. A shell can send it to a file with > or to another program with |., where Console.WriteLine writes, is for the results; standard errorstandard error: A second output stream, for messages about problems, written with Console.Error. It reaches the terminal even when standard output goes to a file, and a shell redirects it on its own with 2>., where Console.Error.WriteLine writes, is for messages about problems. Both appear in a terminal, but a shell can send each one somewhere else, so a result saved to a file never has an error message mixed into it. This version of the marks tool reports every line it cannot use and ends with an exit status that says whether the input was clean:

using System.Globalization;

// Adds up the marks on standard input and reports, on standard error, every line it cannot use.
int count = 0, total = 0, bad = 0, lineNumber = 0;
string? line;
while ((line = Console.ReadLine()) is not null)
{
    lineNumber++;
    if (string.IsNullOrWhiteSpace(line))
    {
        continue;
    }
    if (int.TryParse(line, NumberStyles.Integer, CultureInfo.InvariantCulture, out int mark))
    {
        total += mark;
        count++;
    }
    else
    {
        Console.Error.WriteLine($"line {lineNumber}: not a whole number: \"{line}\"");
        bad++;
    }
}
Console.WriteLine($"{count} marks, total {total}");
return bad == 0 ? 0 : 1;

72
85
9O

90
absent

3 marks, total 247

line 3: not a whole number: "9O"
line 6: not a whole number: "absent"

The run printed 3 marks, total 247 on standard output and two lines on standard error, for lines 3 and 6, and its last line, return bad == 0 ? 0 : 1;, made the exit status 1. Step through where each line went:

The shell does the sending. In Bash and zsh, the Bash manual’s redirections work like this:

The exit status is the third channel, and the one scripts read: 0 for success and anything else for failure, which &&, if and build servers test. Return it from your top-level code, as sum.cs does. The other way, setting Environment.ExitCode and letting the program run to its end, works only when the top-level code returns no number: Microsoft’s reference says the property is ignored when Main returns a value.

Culture decides how numbers look, so choose it yourself

Every formatting and parsing call that is not given a culture uses CultureInfo.CurrentCulture, which comes from the settings of the computer the program runs on. On the Mac that ran this lesson’s sessions, the variable LC_ALL set it, which lets this session run the same program as if on four computers set up for four countries, then a second program, invariant, that names its culture itself:

using System.Globalization;

// Prints a total and reads a price the way the culture of the computer says.
decimal total = 1234567.5m;
Console.WriteLine($"Culture:  {CultureInfo.CurrentCulture.Name}");
Console.WriteLine($"Total:    {total:N2}");
Console.WriteLine($"As money: {total:C}");
Console.WriteLine($"Parsed:   {decimal.Parse("2.50")}");

using System.Globalization;

// The same total and price, printed and read with the invariant culture.
CultureInfo invariant = CultureInfo.InvariantCulture;
decimal total = 1234567.5m;
Console.WriteLine($"Culture:  {CultureInfo.CurrentCulture.Name}");
Console.WriteLine(string.Create(invariant, $"Total:    {total:N2}"));
Console.WriteLine(string.Create(invariant, $"Parsed:   {decimal.Parse("2.50", invariant)}"));

from session import run

# culture formats and parses with the culture of the computer; invariant passes CultureInfo.InvariantCulture. Each
# program runs with LC_ALL set to another culture, as on four computers set up for four countries.
run("""
cd culture
dotnet build -v q
LC_ALL=en_US.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
LC_ALL=en_IN.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
LC_ALL=de_DE.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
!LC_ALL=fr_FR.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
cd ../invariant
dotnet build -v q
LC_ALL=de_DE.UTF-8 dotnet bin/Debug/net10.0/Invariant.dll
LC_ALL=fr_FR.UTF-8 dotnet bin/Debug/net10.0/Invariant.dll
""")

$ cd culture
$ dotnet build -v q

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed …
$ LC_ALL=en_US.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
Culture:  en-US
Total:    1,234,567.50
As money: $1,234,567.50
Parsed:   2.50
$ LC_ALL=en_IN.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
Culture:  en-IN
Total:    12,34,567.50
As money: ₹12,34,567.50
Parsed:   2.50
$ LC_ALL=de_DE.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
Culture:  de-DE
Total:    1.234.567,50
As money: 1.234.567,50 €
Parsed:   250
$ LC_ALL=fr_FR.UTF-8 dotnet bin/Debug/net10.0/Culture.dll
Culture:  fr-FR
Total:    1 234 567,50
As money: 1 234 567,50 €
Unhandled exception. System.FormatException: The input string '2.50' was not in a correct format.
   at System.Number.ThrowFormatException[TChar](ReadOnlySpan`1 value)
   at System.Number.ParseDecimal[TChar](ReadOnlySpan`1 value, NumberStyles styles, NumberFormatInfo info)
   at Program.<Main>$(String[] args) in culture/Program.cs:line 8
[exit status 134]
$ cd ../invariant
$ dotnet build -v q

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed …
$ LC_ALL=de_DE.UTF-8 dotnet bin/Debug/net10.0/Invariant.dll
Culture:  de-DE
Total:    1,234,567.50
Parsed:   2.50
$ LC_ALL=fr_FR.UTF-8 dotnet bin/Debug/net10.0/Invariant.dll
Culture:  fr-FR
Total:    1,234,567.50
Parsed:   2.50

The total printed as 1,234,567.50 in en-US, 12,34,567.50 in en-IN, 1.234.567,50 in de-DE and with spaces in fr-FR. Parsing was worse. decimal.Parse("2.50") gave 2.50 in en-US and en-IN, 250 in de-DE, where the dot groups thousands, and in fr-FR it threw a FormatException that ended the program. A data file read on the wrong computer is either rejected or, worse, read wrong without a word. The second program passes CultureInfo.InvariantCulture, the invariant cultureinvariant culture: CultureInfo.InvariantCulture: a culture tied to no country that formats and parses the same way on every computer, with a dot for decimals and a comma between thousands. Use it for text that programs exchange., to every call, and printed 1,234,567.50 and 2.50 under de-DE and fr-FR alike.

The rule that follows from those runs:

For interpolated strings, string.Create(CultureInfo.InvariantCulture, $"…") formats every value in the string with the invariant culture, as the second program does.

Arguments are checked before any work starts

A tool learns what to do from its arguments, and a wrong argument is a different failure from bad data: the person who typed the command made a mistake, and the right answer is a short usage line. grades takes a pass mark as its only argument, reads marks from standard input and counts how many reach it:

using System.Globalization;

// grades <pass-mark>: reads one mark per line from standard input and counts how many reach the pass mark.
// Exit status: 0 when every line was a mark, 1 when a line was not, 2 when the arguments are wrong.
if (args.Length != 1
    || !int.TryParse(args[0], NumberStyles.Integer, CultureInfo.InvariantCulture, out int passMark)
    || passMark is < 0 or > 100)
{
    Console.Error.WriteLine("usage: grades <pass-mark>, a whole number from 0 to 100");
    return 2;
}

int passed = 0, failed = 0, bad = 0, lineNumber = 0;
string? line;
while ((line = Console.ReadLine()) is not null)
{
    lineNumber++;
    if (string.IsNullOrWhiteSpace(line))
    {
        continue;
    }
    if (int.TryParse(line, NumberStyles.Integer, CultureInfo.InvariantCulture, out int mark) && mark is >= 0 and <= 100)
    {
        if (mark >= passMark)
        {
            passed++;
        }
        else
        {
            failed++;
        }
    }
    else
    {
        Console.Error.WriteLine($"line {lineNumber}: not a mark from 0 to 100: \"{line}\"");
        bad++;
    }
}
Console.WriteLine($"{passed} passed, {failed} failed (pass mark {passMark})");
return bad == 0 ? 0 : 1;

The first statement checks the argument three ways: exactly one, a whole number, and from 0 to 100. Step through the checks for three ways of starting it:

The session runs the tool as a user would. The output of the last run goes to two files, so its two streams can be read apart:

from session import run

# grades run five times: with no argument, with a word for the pass mark, on clean input, and on input with two bad
# lines, first to the terminal and then with its two output streams sent to two files.
run("""
cd grades
dotnet build -v q
!dotnet run
!dotnet run -- forty
dotnet run -- 40 < clean.txt
!dotnet run -- 40 < marks.txt
!dotnet run -- 40 < marks.txt > passed.txt 2> problems.txt
cat passed.txt
cat problems.txt
""")

$ cd grades
$ dotnet build -v q

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed …
$ dotnet run
usage: grades <pass-mark>, a whole number from 0 to 100
[exit status 2]
$ dotnet run -- forty
usage: grades <pass-mark>, a whole number from 0 to 100
[exit status 2]
$ dotnet run -- 40 < clean.txt
2 passed, 1 failed (pass mark 40)
$ dotnet run -- 40 < marks.txt
line 3: not a mark from 0 to 100: "9O"
line 6: not a mark from 0 to 100: "105"
2 passed, 1 failed (pass mark 40)
[exit status 1]
$ dotnet run -- 40 < marks.txt > passed.txt 2> problems.txt
[exit status 1]
$ cat passed.txt
2 passed, 1 failed (pass mark 40)
$ cat problems.txt
line 3: not a mark from 0 to 100: "9O"
line 6: not a mark from 0 to 100: "105"

No argument and the word forty both printed the usage line and ended with exit status 2. The clean input passed with 0. marks.txt held 9O and 105, so the tool reported both on standard error, still counted the rest and ended with 1. With > passed.txt 2> problems.txt, the result and the problems landed in separate files. Three exit statuses now mean three things: 0 success, 1 bad data, 2 wrong usage. Bash itself uses 2 the same way: its manual says its builtins return 2 to indicate incorrect usage.

Practise: a marks summary

Write a file-based app that reads lines such as 101,Asha,72 from standard input: a roll number, a name and a mark. It prints how many lines were valid, the average to two decimals in the invariant culture and the name of the topper; it reports every invalid line on standard error with its line number; and it exits with 1 if any line was invalid. Run it on clean input first, then add a blank line, a mark of 9O, a line with two fields and an empty input, and check its exit status each time with echo $?.

Then work through the questions on the five ideas of this lesson: weaker ideas come first, and every answer arrives with its reason:

Interview questions

Fresher · Why does Console.ReadLine() return a nullable string, string??

Because it has two kinds of answer. While input remains, it returns the next line without its line ending, which can be "" for an empty line. When no lines are left, because a redirected file or a pipe has ended or the user ended the input at the keyboard, with Ctrl+D at the start of a line on macOS and Linux or Ctrl+Z then Enter on Windows, it returns null. With nullable reference types switched on, string? makes the compiler warn wherever you use the result without checking it, as CS8602 does for line.Trim(). The usual loop is while ((line = Console.ReadLine()) is not null) { … }, which stops exactly at the end of the input and treats an empty line as a line.

Key takeaways

• Console.ReadLine() returns null when the input has ended, so read in a loop until null and treat "" as a blank line, not as the end.
• int.Parse throws FormatException or OverflowException on text it cannot read, while TryParse returns false, so bad input becomes a decision in your code.
• Results go to standard output and problems to standard error, so that a shell can send them to different places, and the exit status tells the caller whether it worked.
• Without a culture, formatting and parsing follow the computer: 2.50 became 250 in de-DE, so files and logs use CultureInfo.InvariantCulture.
• Check arguments before any work and answer misuse with a usage line on standard error and exit status 2, keeping 1 for bad data and 0 for success.