XConsole 1.4.2

XConsole

Extended .NET console with coloring microsyntax, multiline pinning, write-to-position & most useful utils. It’s designed with a focus on performance for professional use in complex tasks: a huge number of asynchronous logs, with the need to highlight important and pin summary data. XConsole is safe for multitasking, safe for console buffer overflows (9000+ lines), very easy to use.

The main features are shown in the following image:

<br><br>

• Install
• Setup
• Coloring
• Pinning
• Positioning
• ReadLine
• License <br><br><br>

<a name="install"></a>Install

By Package Manager or by adding package reference to *.csproj file:

PM> Install-Package XConsole

<PackageReference Include="XConsole" Version="1.4.*" />

More ways to install see on NuGet Gallery. <br><br><br>

<a name="setup"></a>Setup

Simple way to start using the XConsole is by adding using to your code. After that you can write Console as usual and get all the features of XConsole. Alternatively, you can upgrade an entire project to XConsole at once by adding the following lines to the *.csproj file.

// Safely upgrade a single code file to XConsole
using Console = Chubrik.XConsole.XConsole;

<ItemGroup>
  
  <Using Include="Chubrik.XConsole.XConsole" Alias="Console" />
</ItemGroup>

This trick is great for upgrading an existing regular console application because XConsole is backwards compatible with the standard Console. After the upgrade, the application will not change how it works unless you want to start using the XConsole features. <br><br><br><br>

<a name="coloring"></a>Coloring

Standard console colors

To colorize the text with standard console colors you need to add a prefix to a string. The prefix consists of one or two letters denoting colors, followed by a trailing ` character, after which the text immediately begins. Let’s denote the text color letter as T and the background color letter as B. In this case, there are three prefix patterns: T` to change only text color, TB` to change text and background colors,  B` (space at the beginning) to change only background color. To make a multicolor message split it to parts with individual color prefixes and pass them to single WriteLine method. Be sure that your messages will not be broken by other threads.

Console.WriteLine("G`This line is colorized using simple microsyntax");                 // Single color
Console.WriteLine("C`It is easy ", "Wb`to use many", "R` colors in ", "Y`one message"); // Multicolor

The following table shows all standard console colors and their letter designations:

<br>

Extended colors

If you’re running your application on Windows 10+ with .NET 5+, extended colors are available to you:

// Different ways to colorize text the same orange color
Console.WriteLine("This is orange text".Color(Color.Orange)); // Color structure
Console.WriteLine("This is orange text".Color(255, 165, 0));  // Red, green & blue
Console.WriteLine("This is orange text".Color(0xFFA500));     // Hexadecimal number
Console.WriteLine("This is orange text".Color("#FFA500"));    // Hexadecimal string

// Combinations of text and background colors
Console.WriteLine("This is orange with an indigo background.".Color(Color.Orange).BgColor(Color.Indigo));
Console.WriteLine(("This is lime " + "with a brown".BgColor(Color.Brown) + " background.").Color(Color.Lime));
Console.WriteLine($"This is aqua {"with a navy".BgColor(Color.Navy)} background.".Color(Color.Aqua));

NO_COLOR

XConsole supports the NO_COLOR standard with an environment variable and with a property.

Console.NO_COLOR = true; // Disable all colors

<br><br>

<a name="pinning"></a>Pinning

You can pin some text below regular log messages with the Pin method. Pinned text can be static or dynamic, contain one or more lines, and of course can be colorized. Pin is resistant to line wrapping and to console buffer overflows (9000+ log lines).

Static pin

Console.Pin("Simple static pin");           // Simple static pin
Console.Pin("Y`Multicolor", " static pin"); // Multicolor static pin
Console.Pin("Multiline\nstatic pin");       // Multiline static pin

Dynamic pin

Console.Pin(() => "Simple pin, value=" + value);                           // Simple dynamic pin
Console.Pin(() => new[] { "Y`Multicolor", " pin, value=", "C`" + value }); // Multicolor dynamic pin
Console.Pin(() => new[] { "Multiline pin,\nvalue=", "C`" + value });       // Multiline dynamic pin

The dynamic pin will be automatically updated every time the Write or WriteLine methods are called. You can also update a dynamic pin manually using the UpdatePin method. To remove a pin, call the Unpin method.

Console.UpdatePin(); // Update dynamic pin manually
Console.Unpin();     // Remove pin

<br><br>

<a name="positioning"></a>Positioning

XConsole provides a ConsolePosition structure, which is a position in the console area. This is an important feature if you have a lot of log messages. This structure is resistant to console buffer overflows (9000+ log lines) and always points to the correct position in the console area. Each Write and WriteLine method returns a start and end position. You can save them and use later to rewrite the text or add text to the end of the message. To do this, ConsolePosition has its own Write method, which returns a new end position.

NB! The end position of WriteLine means the position after the last character before the line break.

var (begin, end) = Console.WriteLine("Hello, World!"); // Write message and save positions

begin.Write("C`HELLO");       // Rewrite part of text
end = end.Write(" I'm here"); // Add text to the end and update end position
end.Write("Y`!");

<br><br> You can also get or set the cursor position using the CursorPosition property:

ConsolePosition position = Console.CursorPosition;              // Get cursor position
Console.CursorPosition = new ConsolePosition(left: 15, top: 5); // Set cursor position

<br><br>

<a name="readline"></a>ReadLine

ReadLine has two additional modes for secure input: masked and hidden. Mask symbol is customizable.

Console.ReadLine(ConsoleReadLineMode.Masked);                // Masked ReadLine
Console.ReadLine(ConsoleReadLineMode.Masked, maskChar: '#'); // Masked ReadLine with custom mask
Console.ReadLine(ConsoleReadLineMode.Hidden);                // Hidden ReadLine

<br><br><br>

<a name="license"></a>License

The XConsole is licensed under the MIT license. <br><br>