Upload

README.md

@@ -0,0 +1,167 @@
+# NETLogger
+
+NETLogger is a small logging library for .NET applications targeting .NET Standard 2.0.
+
+## Installation
+
+Add `NETLogger/NETLogger.csproj` as a project reference or install the NuGet package generated during the build.
+
+## Configure the application
+
+Configure the global logger settings once during application startup. The following example stores log files in the current user's application data directory:
+
+```csharp
+using NETLogger;
+
+LogConfiguration.MinimumLevel = LogLevel.Info;
+LogConfiguration.EnableConsole = true;
+LogConfiguration.EnableDebugView = true; // Windows only
+
+string logDirectory = LogConfiguration.CreateAndGetDefaultLoggingPath("MyApplication");
+LogConfiguration.GetAndSetNewLogFile(logDirectory);
+```
+
+Alternatively, use `LogConfiguration.SetLogFile(path)` to specify a complete file path. Without a configured file path, NETLogger writes only to the enabled console and Windows debug outputs.
+
+## Use a logger directly
+
+For an independent class, create a typed `Logger<T>`. The type name is automatically included in each log entry as its category:
+
+```csharp
+public class Service
+{
+	private readonly ILogger _logger = new Logger<Service>();
+
+	public void Run()
+	{
+		_logger.Info("Service started.");
+
+		try
+		{
+			// Application code
+		}
+		catch (Exception exception)
+		{
+			_logger.Error("Service failed.", exception);
+		}
+	}
+}
+```
+
+A directly created `Logger<T>` can be disabled and enabled independently with `Disable()` and `Enable()`. `ClearOldLogs(logsToKeep)` removes old log files; without an argument, it keeps the 30 most recent files. `ClearLogs()` removes all log files from the configured directory.
+
+## Control multiple loggers centrally
+
+Use a shared `LoggerControlService` when multiple loggers need to be enabled or disabled together. An owning class creates the service and registers its logger:
+
+```csharp
+using NETLogger;
+using NETLogger.Services;
+
+public sealed class ApplicationController : IDisposable
+{
+	private readonly ILoggerControlService _loggerControlService;
+	private readonly ILogger<ApplicationController> _logger;
+	private readonly IDisposable _loggerRegistration;
+
+	public ILoggerControlService LoggerControlService => _loggerControlService;
+
+	public ApplicationController() : this(new LoggerControlService()) { }
+
+	public ApplicationController(ILoggerControlService loggerControlService)
+	{
+		_loggerControlService = loggerControlService
+			?? throw new ArgumentNullException(nameof(loggerControlService));
+
+		_logger = NETLogger.Services.LoggerControlService.CreateAndRegisterNETLogger<ApplicationController>(
+			_loggerControlService,
+			out _loggerRegistration);
+
+		_logger.Info("Application controller initialized.");
+	}
+
+	public void Dispose()
+	{
+		_loggerRegistration.Dispose();
+	}
+}
+```
+
+Dependent classes receive the same service and register their own typed logger. Dispose the `IDisposable` registration when the owning instance is disposed:
+
+```csharp
+public sealed class BackgroundService : IDisposable
+{
+	private readonly ILogger<BackgroundService> _logger;
+	private readonly IDisposable _loggerRegistration;
+
+	public BackgroundService(ILoggerControlService loggerControlService)
+	{
+		_logger = LoggerControlService.CreateAndRegisterNETLogger<BackgroundService>(
+			loggerControlService,
+			out _loggerRegistration);
+
+		_logger.Info("Background service initialized.");
+	}
+
+	public void Dispose()
+	{
+		_loggerRegistration.Dispose();
+	}
+}
+```
+
+All registered loggers can be toggled together:
+
+```csharp
+loggerControlService.IsEnabled = false; // Disable all registered loggers
+loggerControlService.IsEnabled = true;  // Enable all registered loggers
+```
+
+## Initialize loggers for static members
+
+Classes with static logging members can use explicit initialization to participate in the shared `LoggerControlService`:
+
+```csharp
+public sealed class ConfigurationCache
+{
+	private static ILogger<ConfigurationCache> _logger;
+	private static IDisposable _loggerRegistration;
+
+	private ConfigurationCache() { }
+
+	public static void InitializeLogger(ILoggerControlService loggerControlService)
+	{
+		if (loggerControlService == null)
+			throw new ArgumentNullException(nameof(loggerControlService));
+
+		_loggerRegistration?.Dispose();
+		_logger = LoggerControlService.CreateAndRegisterNETLogger<ConfigurationCache>(
+			loggerControlService,
+			out _loggerRegistration);
+	}
+}
+```
+
+The owning class initializes the logger with its shared service:
+
+```csharp
+ConfigurationCache.InitializeLogger(_loggerControlService);
+```
+
+## Log levels and outputs
+
+The available levels are `Trace`, `Debug`, `Info`, `Warn`, `Error`, and `Fatal`. Messages below `LogConfiguration.MinimumLevel` are ignored. `Warn`, `Error`, and `Fatal` optionally accept an exception:
+
+```csharp
+try
+{
+	// Application code
+}
+catch (Exception exception)
+{
+	_logger.Error("Operation failed.", exception);
+}
+```
+
+NETLogger can write to the Windows debug output, the console, and a UTF-8 log file at the same time.