ConsoleDebugger 1.0.5

ConsoleDebugger

Overview

ConsoleDebugger is a lightweight utility designed for console applications that involve multiple asynchronous operations, background processes, and network activities. It provides functionalities to log debug messages, play audible beeps, and dynamically track float variables with a continuous tone, making it useful for debugging and monitoring applications with complex behavior. ConsoleDebugger is ideal for console applications where you have multiple asynchronous methods, background processes, or network operations and need a way to keep track of multiple moving parts.

Installation

To use ConsoleDebugger in your C# console application, follow these steps:

1. Install the ConsoleDebugger package via NuGet Package Manager:

dotnet add package ConsoleDebugger --version 1.0.5

2. Include using static ConsoleDebugger.ConsoleDebugger; or optionally for a more functional approach global using static ConsoleDebugger.ConsoleDebugger;.

Usage

Logging Debug Messages

You can log debug messages with different colors and message types using the DebugMessage function:

Result result = SomeNetworkFunction(); // example function
ConsoleDebugger.DebugMessage("We started the network function.");
if(result == Good){
   //denote network results in blue
   ConsoleDebugger.DebugMessage($"Here's the results {result}", ConsoleColor.Blue);
} else {
   ConsoleDebugger.DebugMessage("Critical error occurred: {result.Message}", MessageType.Critical);
}

Optional File Logging

You can enable file logging for debug messages by calling the StartLogging function:

ConsoleDebugger.StartLogging();

To stop file logging, use the StopLogging function:

ConsoleDebugger.StopLogging();

File logging is configured in the LoggingConfiguration class, where you can set options such as log style (CSV or plain text) and timestamp inclusion.

Note: Ensure proper error handling and file management practices when using file logging to avoid potential issues with file access and resources.

Logging Categories

The ConsoleDebugger supports logging categories to help filter and manage the messages you want to see. Each logging message can be associated with a specific category. By default, all messages without an explicitly defined category are assigned to the "General" category.

Defining and Using Logging Categories

A logging category is represented by the LoggingCategory record struct. You can create custom categories and control which categories are active or inactive, allowing you to filter messages at runtime.

1. Adding and Removing Categories

• Add a Category: Use AddLoggingCategory to add a new logging category. By default, the new category is active.

  // Create a custom category called "Network"
  var networkCategory = new ConsoleDebugger.LoggingCategory("Network");
  ConsoleDebugger.AddLoggingCategory(networkCategory);
  

• Remove a Category: Remove an existing category with RemoveLoggingCategory.

  // Remove the "Network" category when it's no longer needed
  ConsoleDebugger.RemoveLoggingCategory(networkCategory);
  

2. Activating and Deactivating Categories

• Activate a Category: If a category has been deactivated, you can re-enable it using ActivateLoggingCategory.

  // Activate the Network category
  ConsoleDebugger.ActivateLoggingCategory(networkCategory);
  

• Deactivate a Category: Temporarily suppress messages from a particular category with DeactivateLoggingCategory.

  // Deactivate the Network category so that its messages are not processed
  ConsoleDebugger.DeactivateLoggingCategory(networkCategory);
  

• Check Category Status: Use the LoggingCategoryActive method to determine if a category is currently active. If inactive, messages will be skipped and not shown in the console.

  bool isNetworkActive = ConsoleDebugger.LoggingCategoryActive(networkCategory);
  Console.WriteLine($"Is Network logging active? {isNetworkActive}");
  

3. Logging Messages with a Category

When logging a message, you can specify the category to which the message belongs. If no category is provided, the message defaults to "General".

// Logging a message to the General category.
ConsoleDebugger.DebugMessage("General debug message");

// Logging a message to a custom category (e.g., "Network")
ConsoleDebugger.DebugMessage("Network request started...", networkCategory);

Note: If a logging category is deactivated, messages associated with that category will not be printed to the console, but will still be logged to the file.

Playing Audible Beeps

You can enqueue requests to play audible beeps with specific pitches and durations using the DebugBeep function:

ConsoleDebugger.DebugBeep(TonePitch.Do, ToneLength.Short);
ConsoleDebugger.DebugBeep(TonePitch.Re, ToneLength.Short);
ConsoleDebugger.DebugBeep(TonePitch.Mi, ToneLength.Medium);
ConsoleDebugger.DebugBeep(TonePitch.Fa, ToneLength.Medium);
ConsoleDebugger.DebugBeep(TonePitch.Sol, ToneLength.Long);

Tracking Float Variables

You can start tracking float variables dynamically and generate tones based on their values using the StartTrackingFloat function:

float valueToTrack = 0.0f;
FloatSynthesizer synthesizer = ConsoleDebugger.StartTrackingFloat(ref valueToTrack, 0.0f, 100.0f);

or

float valueToTrack = 0.0f;
StartTrackingFloat(ref valueToTrack, 0.0f, 100.0f);

As valueToTrack fluctuates, it will become more audible the closer to the maximum value that it gets. The closer it gets to the minimum value, the less audible and more quiet it will become. This can be useful in scenarios where you may be receiving large quantities of representative data within a certain range, or may be preforming algorithmic operations, and need some way to better understand how the values are being effected.

Functions Details

DebugMessage(string message)

Enqueues a basic debug message to the processing queue.

DebugMessage(string message, ConsoleColor color)

Enqueues a debug message with a specified foreground color.

DebugMessage(string message, MessageType type)

Enqueues a debug message with an associated message type (General, Warning, Critical).

DebugBeep(TonePitch pitch, ToneLength duration)

Enqueues a request to play an audible beep with a specified pitch and duration.

StartTrackingFloat(ref float target, float minrange, float maxrange) : FloatSynthesizer

Begins monitoring a float variable, generating a tone whose pitch changes dynamically based on the variable's value within a specified range.

License

This project is licensed under the MIT License.