Repository navigation
Log BlueprintLog
BlueprintLog is the abstract base class for application logging in the Blueprint.Log namespace. It defines the shared API for writing, reading, counting, paginating, and deleting events. It cannot be instantiated directly; create a concrete implementation and use it through a BlueprintLog reference.
The base class captures Environment.MachineName once during construction and exposes it through the read-only MachineName property. WriteToLog, ReadFromLog, CountFromLog, and DeleteFromLog are abstract methods: the concrete implementation supplies persistence, queries, deletion, and argument validation according to their contract. The base class does not open database connections or create storage.
| Implementation | Status | Documentation |
|---|---|---|
SqlLog |
Available; implements logging in SQL Server. | SqlLog: initialization, examples, SQL table, permissions, and execution behavior. |
MySqlLog |
Coming Soon; not implemented yet. | MySqlLog (Coming Soon): reserved for MySQL logging configuration and usage. |
Application code can depend on BlueprintLog while choosing the concrete implementation during initialization. For a working example, see Create a SQL log. Connection settings, table creation, timestamp generation and precision, and transaction behavior belong to the implementation's documentation.
| Property | Purpose |
|---|---|
| MachineName | Gets the originating machine name captured when this log instance was created. |
Type: string. Access: read-only.
The value of Environment.MachineName captured once by the base constructor. Each event written through this instance records that machine name. It has no setter and is not supplied as an argument to WriteToLog.
Read it through log.MachineName, for example when requesting events from the current machine. Reading the property does not access stored events. Reads and counts include all machines unless the caller explicitly supplies a machine-name filter.
| Method | Purpose |
|---|---|
| WriteToLog(level, message, logger, exception) | Persists one event with its level, message, optional source, and optional exception. |
| ReadFromLog(...) | Reads events by UTC interval, optionally filtering by level and machine, with unpaged or paged results. |
| CountFromLog(...) | Counts matching events before pagination using the same interval, level, and machine filters. |
| DeleteFromLog(dateTimeUtcBefore) | Deletes all events strictly before a UTC cutoff, across all levels and machines. |
All four methods are abstract; the selected log provider implements persistence, queries, and deletion. The examples below assume an initialized BlueprintLog variable named log. See Create a SQL log for initialization. Examples are independent and use these imports as needed:
using Blueprint.Log;
using System;
using System.Collections.Generic;The shared method is WriteToLog(EBlueprintLogLevel level, string message, string? logger = null, Exception? exception = null) and returns void.
| Parameter | Type | Meaning |
|---|---|---|
level |
EBlueprintLogLevel |
A defined log level chosen by the caller. |
message |
string |
The final message; it must not be null, empty, or whitespace-only. |
logger |
string? |
An optional source label of up to 500 characters; defaults to null. |
exception |
Exception? |
An optional exception associated with the event; defaults to null. |
The contract requires the event to be persisted before the call returns, with an automatically assigned UTC timestamp and the originating machine name. Callers do not supply a timestamp or machine name to this method. Persistence failures propagate to the caller.
Write a normal event or add a source label:
log.WriteToLog(EBlueprintLogLevel.Info, "Application started.");
log.WriteToLog(EBlueprintLogLevel.Warn, "Product 320 has no image.", "ProductImport");To record a failure, pass the exception along with a message describing the failed operation:
try
{
string contents = System.IO.File.ReadAllText("products.csv");
log.WriteToLog(EBlueprintLogLevel.Info, $"Read {contents.Length} characters from products.csv.", "ProductImport");
}
catch (System.IO.IOException exception)
{
log.WriteToLog(EBlueprintLogLevel.Error, "Could not read products.csv.", "ProductImport", exception);
}See SqlLog: Write an event for SQL Server timestamp behavior and exception storage.
ReadFromLog returns IReadOnlyList<LogEntry> in descending insertion Id order. Its overloads accept the following arguments:
| Parameter | Type | Meaning |
|---|---|---|
dateTimeUtcFrom |
DateTime |
The inclusive start of the UTC interval. |
dateTimeUtcTo |
DateTime |
The exclusive end of the UTC interval. |
level |
EBlueprintLogLevel |
One exact level, when using an overload with a level filter. |
machineName |
string |
The originating machine, when using an overload with both level and machine filters. |
skip |
int |
The nonnegative number of matching entries to skip in a paged overload. |
take |
int |
The positive maximum number of entries to return in a paged overload. |
The three unpaged overloads read all matching events:
| Overload | Filters |
|---|---|
ReadFromLog(dateTimeUtcFrom, dateTimeUtcTo) |
The UTC interval, across all levels and machines. |
ReadFromLog(dateTimeUtcFrom, dateTimeUtcTo, level) |
The UTC interval and exactly one level. |
ReadFromLog(dateTimeUtcFrom, dateTimeUtcTo, level, machineName) |
The UTC interval, exactly one level, and the supplied machine name. |
Both boundaries are DateTime values with Kind = DateTimeKind.Utc. The start is inclusive and the end is exclusive: dateTimeUtcFrom <= Logged < dateTimeUtcTo. A reversed interval or a non-UTC boundary is invalid. Equal boundaries return an empty list.
The level filter selects one exact EBlueprintLogLevel, not a minimum severity. When supplied, machineName must be nonempty, not whitespace-only, and no longer than 255 characters. Reads are not automatically restricted to the current instance's MachineName.
Results are read-only snapshots containing immutable LogEntry objects. No matches produce an empty list, never null. Unpaged reads have no implicit row limit. Reading failures propagate rather than being returned as empty results.
For example, read the current UTC day with each filter combination:
DateTime fromUtc = DateTime.UtcNow.Date;
DateTime toUtc = fromUtc.AddDays(1);
IReadOnlyList<LogEntry> events = log.ReadFromLog(fromUtc, toUtc);
IReadOnlyList<LogEntry> errors = log.ReadFromLog(fromUtc, toUtc, EBlueprintLogLevel.Error);
IReadOnlyList<LogEntry> machineErrors = log.ReadFromLog(fromUtc, toUtc, EBlueprintLogLevel.Error, log.MachineName);
Console.WriteLine($"Events: {events.Count}; errors: {errors.Count}; errors from this machine: {machineErrors.Count}");
foreach (LogEntry entry in machineErrors)
{
Console.WriteLine($"{entry.Logged:O} [{entry.Level}] {entry.Message}");
}See SqlLog: Read events for SQL Server filtering details.
To read a page, append skip and take to the corresponding read call:
| Overload | Result |
|---|---|
ReadFromLog(dateTimeUtcFrom, dateTimeUtcTo, skip, take) |
A page across all levels and machines. |
ReadFromLog(dateTimeUtcFrom, dateTimeUtcTo, level, skip, take) |
A page for exactly one level. |
ReadFromLog(dateTimeUtcFrom, dateTimeUtcTo, level, machineName, skip, take) |
A page for exactly one level and machine. |
skip is a nonnegative int; take is a positive int. Paged reads return IReadOnlyList<LogEntry> in descending Id order after applying the filters. A page beyond the matching events is empty, and the last page may contain fewer than take entries.
For example, request the first 25 matching entries with each filter combination:
DateTime fromUtc = DateTime.UtcNow.Date;
DateTime toUtc = fromUtc.AddDays(1);
int skip = 0;
int take = 25;
IReadOnlyList<LogEntry> page = log.ReadFromLog(fromUtc, toUtc, skip, take);
IReadOnlyList<LogEntry> errorPage = log.ReadFromLog(fromUtc, toUtc, EBlueprintLogLevel.Error, skip, take);
IReadOnlyList<LogEntry> machineErrorPage = log.ReadFromLog(fromUtc, toUtc, EBlueprintLogLevel.Error, log.MachineName, skip, take);
Console.WriteLine($"Page entries: {page.Count}; errors: {errorPage.Count}; errors from this machine: {machineErrorPage.Count}");Use CountFromLog with the same filters to obtain the total number of matching events before pagination.
CountFromLog returns a long with the total number of matching events before pagination. It supports the same filter combinations as reads:
| Overload | Filters |
|---|---|
CountFromLog(dateTimeUtcFrom, dateTimeUtcTo) |
The UTC interval, across all levels and machines. |
CountFromLog(dateTimeUtcFrom, dateTimeUtcTo, level) |
The UTC interval and exactly one level. |
CountFromLog(dateTimeUtcFrom, dateTimeUtcTo, level, machineName) |
The UTC interval, exactly one level, and the supplied machine name. |
The parameters have the same types and validation rules as ReadFromLog: UTC DateTime boundaries, an optional exact EBlueprintLogLevel filter, and a machine-name string when using the last overload. No matches or equal boundaries produce zero; counting failures propagate. There are no skip or take arguments because counting always covers the full matching set.
For example, count events for the current UTC day:
DateTime fromUtc = DateTime.UtcNow.Date;
DateTime toUtc = fromUtc.AddDays(1);
long totalCount = log.CountFromLog(fromUtc, toUtc);
long errorCount = log.CountFromLog(fromUtc, toUtc, EBlueprintLogLevel.Error);
long machineErrorCount = log.CountFromLog(fromUtc, toUtc, EBlueprintLogLevel.Error, log.MachineName);
Console.WriteLine($"Events: {totalCount}; errors: {errorCount}; errors from this machine: {machineErrorCount}");See SqlLog: Count and paginate events for a complete grid example and the effects of concurrent writes between count and read calls.
DeleteFromLog(DateTime dateTimeUtcBefore) returns void and deletes every event whose stored timestamp satisfies Logged < dateTimeUtcBefore. Events exactly at the cutoff or later are retained. Deletion covers all levels and machines in this log, including events written by other instances.
The argument must have Kind = DateTimeKind.Utc; local and unspecified values throw ArgumentException without deleting anything. Fractional seconds in the cutoff are preserved. No matching events, including an empty log, is a successful no-op. Storage failures propagate to the caller, and previously returned LogEntry snapshots remain unchanged.
For example, delete events older than thirty days:
DateTime cutoffUtc = DateTime.UtcNow.AddDays(-30);
log.DeleteFromLog(cutoffUtc);Call the method explicitly when cleanup is required; it does not enable a recurring retention policy. Custom BlueprintLog implementations must implement this abstract method. See SqlLog: Delete old events for SQL permissions and transaction behavior.
EBlueprintLogLevel belongs to the Blueprint.Log namespace and defines these values:
| Value | Typical use |
|---|---|
Trace |
Detailed execution diagnostics. |
Debug |
Information used to diagnose problems. |
Info |
Normal application events. |
Warn |
A problem that allows execution to continue. |
Error |
A failed operation. |
Fatal |
A critical failure that prevents the application from continuing. |
The caller chooses the level when writing an event. The shared API has no minimum-level configuration; its read and count filters select one exact level. Undefined enum values are invalid.
LogEntry is the immutable result type in the Blueprint.Log namespace. It exposes these read-only properties:
| Property | Type | Meaning |
|---|---|---|
Id |
long |
The database-generated insertion ID. |
Logged |
DateTime |
The stored UTC timestamp, returned with Kind = DateTimeKind.Utc. |
Level |
EBlueprintLogLevel |
The stored event level. |
Message |
string |
The stored message. |
Logger |
string? |
The source label, or null. |
Exception |
string? |
The stored exception text, or null. |
MachineName |
string |
The machine name recorded by the writer. |
Reading does not reconstruct the original Exception object. Later writes do not modify an already returned entry or result collection. See SqlLog: SQL table for the SQL Server column types and timestamp precision.