In the .NET Console interface, most input is done through the standard input handle, using the high-level input API function ReadConsole, which is called by Console.Read and Console.ReadLine. Two lower level methods, KeyAvailable and ReadKey let you poll the console for available input and get (mostly) raw keystroke data—provided that the standard input handle has not been redirected.

Although sufficient for some programs, the input methods provided by the .NET Console class do not provide access to all of the Windows Console input functionality. In this article, I describe the input functions available in the Windows Console interface and show how to use the ConsoleInputBuffer class to write programs that take full advantage of those functions.

Be sure to read the earlier articles in this series about .NET Console programming: Working with Console Screen Buffers in .NET and Extending the .NET Console Interface.

About Input Buffers

Every console window has one console input buffer that contains a queue of input event records. When the application has the keyboard focus, the console subsystem captures input events (keystrokes, mouse clicks and movements, and a few others), formats them, and places the records into the queue.

Applications can access the input buffer indirectly through high-level input functions, or directly by calling the low-level input functions.

To access console input, an application must obtain a handle to the console input buffer by calling CreateFile to open the special file "CONIN$". By default, the standard input handle is the console input buffer. Although applications can redirect standard input (i.e. the standard input handle), the console input buffer still exists and can be used to obtain keyboard and mouse events. The .NET System.Console class, however, prevents this by throwing an exception if you try to access the input buffer when the standard input is redirected.

High-level Input

The high-level input function ReadConsole returns Unicode characters, and therefore cannot be used to obtain function keys, Alt-key combinations, or other special keys. In addition, the default input mode enables certain functionality that facilitates using the high-level functions. The following four modes are enabled by default:

• Processed input mode causes the system to process system editing and control key input rather than returning it as a character. In particular, the Ctrl+C key combination generates a console control event. If line input mode also is enabled, then editing keys are processed: backspace erases the previous character, Enter is changed to a carriage return and linefeed pair, and other editing keys work as expected.
• Line input mode causes the ReadConsole function to block until the Enter key is pressed. If Line Input is disabled, ReadConsole returns when one or more key events are available.
• Echo Input mode causes keyboard input read by ReadConsole to be echoed to the active screen buffer. Echo mode cannot be enabled unless line input mode also is enabled. The output mode of the active screen buffer affects the way that echoed input is displayed. Usually, if you're using echo input mode, you'll want the screen buffer's processed output mode enabled.
• Insert mode causes text to be inserted at the current cursor position, moving all existing text after that position to the right. When disabled, inserted text will overwrite any existing text on the line. You can toggle insert mode by pressing the Ins key.

Finally, quick edit mode lets the user select and edit text using the mouse. This mode is off by default.

The default console mode settings are ideal for high-level keyboard input. Disabling any one of those three settings will make the high-level input routines act unexpectedly. If you're using high-level input, I suggest that you not change the mode settings.

A side effect of using the high-level input routines is that other input records (mouse events, for example) are discarded from the input queue when the application is waiting to read key events. This isn't generally a problem, but since there's no high-level way to get mouse events, it's something to keep in mind if you want to support mouse events in your character-mode applications.

The System.Console class supports high-level input with the Read and ReadLine methods. Read obtains the next character in the input stream and returns it as an Int32. Programs that use Read can convert that integer to a Unicode character by calling Convert.ToChar.

ReadLine obtains the next line of characters and returns it as a String. The terminating carriage return and linefeed pair is discarded. These functions are designed to work with the default input mode setting and will produce unexpected results if the mode is changed.

The ConsoleInputBuffer class also has Read and ReadLine methods that exactly duplicate the functionality available in System.Console. It was necessary to duplicate these functions in order to provide full input buffer functionality when the standard input handle is redirected.