Merge pull request #5 from EvotecIT/add-documentation-to-iisparser-project

Author: PrzemyslawKlys

IISParser.PowerShell/AsyncPSCmdlet.cs

@@ -7,42 +7,66 @@
 
 namespace IISParser.PowerShell;
 
+/// <summary>
+/// Base class for asynchronous PowerShell cmdlets that exposes asynchronous equivalents
+/// of the standard <see cref="PSCmdlet"/> lifecycle methods.
+/// </summary>
 public abstract class AsyncPSCmdlet : PSCmdlet, IDisposable {
     private readonly CancellationTokenSource _cancelSource = new();
 
     private BlockingCollection<(object?, PipelineType)>? _currentOutPipe;
     private BlockingCollection<object?>? _currentReplyPipe;
 
+    /// <summary>
+    /// Gets a cancellation token that is triggered when the cmdlet is stopped.
+    /// </summary>
     protected internal CancellationToken CancelToken => _cancelSource.Token;
 
+    /// <inheritdoc />
     public void Dispose() {
         _cancelSource?.Dispose();
     }
 
+    /// <inheritdoc />
     protected override void BeginProcessing() {
         RunBlockInAsync(BeginProcessingAsync);
     }
 
+    /// <summary>
+    /// Asynchronously performs initialization before record processing begins.
+    /// </summary>
+    /// <returns>A task representing the asynchronous operation.</returns>
     protected virtual Task BeginProcessingAsync() {
         return Task.CompletedTask;
     }
 
+    /// <inheritdoc />
     protected override void ProcessRecord() {
         RunBlockInAsync(ProcessRecordAsync);
     }
 
+    /// <summary>
+    /// Asynchronously processes each record.
+    /// </summary>
+    /// <returns>A task representing the asynchronous operation.</returns>
     protected virtual Task ProcessRecordAsync() {
         return Task.CompletedTask;
     }
 
+    /// <inheritdoc />
     protected override void EndProcessing() {
         RunBlockInAsync(EndProcessingAsync);
     }
 
+    /// <summary>
+    /// Asynchronously performs cleanup after processing is complete.
+    /// </summary>
+    /// <returns>A task representing the asynchronous operation.</returns>
     protected virtual Task EndProcessingAsync() {
         return Task.CompletedTask;
     }
 
+    /// <inheritdoc />
     protected override void StopProcessing() {
         _cancelSource?.Cancel();
     }
@@ -100,46 +124,85 @@ private void RunBlockInAsync(Func<Task> task) {
         blockTask.GetAwaiter().GetResult();
     }
 
+    /// <summary>
+    /// Determines whether the cmdlet should continue processing.
+    /// </summary>
+    /// <param name="target">The target of the operation.</param>
+    /// <param name="action">The action to be performed.</param>
+    /// <returns><c>true</c> if processing should continue; otherwise, <c>false</c>.</returns>
     public new bool ShouldProcess(string target, string action) {
         ThrowIfStopped();
         _currentOutPipe?.Add(((target, action), PipelineType.ShouldProcess));
         return (bool)_currentReplyPipe?.Take(CancelToken)!;
     }
 
+    /// <summary>
+    /// Writes an object to the output pipeline.
+    /// </summary>
+    /// <param name="sendToPipeline">The object to write.</param>
     public new void WriteObject(object? sendToPipeline) {
         WriteObject(sendToPipeline, false);
     }
 
+    /// <summary>
+    /// Writes an object to the output pipeline with optional enumeration of collections.
+    /// </summary>
+    /// <param name="sendToPipeline">The object to write.</param>
+    /// <param name="enumerateCollection">Whether to enumerate the object if it is a collection.</param>
     public new void WriteObject(object? sendToPipeline, bool enumerateCollection) {
         ThrowIfStopped();
         _currentOutPipe?.Add((sendToPipeline, enumerateCollection ? PipelineType.OutputEnumerate : PipelineType.Output));
     }
 
+    /// <summary>
+    /// Writes an error record to the error pipeline.
+    /// </summary>
+    /// <param name="errorRecord">The error to write.</param>
     public new void WriteError(ErrorRecord errorRecord) {
         ThrowIfStopped();
         _currentOutPipe?.Add((errorRecord, PipelineType.Error));
     }
 
+    /// <summary>
+    /// Writes a warning message to the warning pipeline.
+    /// </summary>
+    /// <param name="message">The warning message.</param>
     public new void WriteWarning(string message) {
         ThrowIfStopped();
         _currentOutPipe?.Add((message, PipelineType.Warning));
     }
 
+    /// <summary>
+    /// Writes a verbose message to the verbose pipeline.
+    /// </summary>
+    /// <param name="message">The verbose message.</param>
     public new void WriteVerbose(string message) {
         ThrowIfStopped();
         _currentOutPipe?.Add((message, PipelineType.Verbose));
     }
 
+    /// <summary>
+    /// Writes a debug message to the debug pipeline.
+    /// </summary>
+    /// <param name="message">The debug message.</param>
     public new void WriteDebug(string message) {
         ThrowIfStopped();
         _currentOutPipe?.Add((message, PipelineType.Debug));
     }
 
+    /// <summary>
+    /// Writes information to the information pipeline.
+    /// </summary>
+    /// <param name="informationRecord">The information record.</param>
     public new void WriteInformation(InformationRecord informationRecord) {
         ThrowIfStopped();
         _currentOutPipe?.Add((informationRecord, PipelineType.Information));
     }
 
+    /// <summary>
+    /// Writes a progress record to the progress pipeline or directly if asynchronous output is not active.
+    /// </summary>
+    /// <param name="progressRecord">The progress record.</param>
     public new void WriteProgress(ProgressRecord progressRecord) {
         ThrowIfStopped();
         if (_currentOutPipe != null) {
@@ -155,6 +218,10 @@ internal void ThrowIfStopped() {
         }
     }
 
+    /// <summary>
+    /// Retrieves the effective <see cref="ActionPreference"/> for error handling.
+    /// </summary>
+    /// <returns>The resolved <see cref="ActionPreference"/>.</returns>
     protected ActionPreference GetErrorActionPreference() {
         if (MyInvocation.BoundParameters.ContainsKey("ErrorAction")) {
             string? errorActionString = MyInvocation.BoundParameters["ErrorAction"]?.ToString();
@@ -175,6 +242,12 @@ protected ActionPreference GetErrorActionPreference() {
         return ActionPreference.Continue;
     }
 
+    /// <summary>
+    /// Ensures that the specified file exists, writing a warning or terminating error as appropriate.
+    /// </summary>
+    /// <param name="path">The file path to check.</param>
+    /// <param name="errorAction">The action preference determining error handling.</param>
+    /// <returns><c>true</c> if the file exists; otherwise, <c>false</c>.</returns>
     protected bool EnsureFileExists(string path, ActionPreference errorAction) {
         if (File.Exists(path)) {
             return true;

IISParser.PowerShell/CmdletGetIISParsedLog.cs

@@ -7,28 +7,47 @@
 
 namespace IISParser.PowerShell;
 
+/// <summary>
+/// PowerShell cmdlet that parses an IIS log file and returns the parsed entries.
+/// </summary>
 [Cmdlet(VerbsCommon.Get, "IISParsedLog", DefaultParameterSetName = "Default")]
 public class CmdletGetIISParsedLog : AsyncPSCmdlet {
     private ParserEngine? _parser;
 
+    /// <summary>
+    /// Gets or sets the path to the IIS log file.
+    /// </summary>
     [Parameter(Mandatory = true, ParameterSetName = "Default")]
     [Parameter(Mandatory = true, ParameterSetName = "FirstLastSkip")]
     [Parameter(Mandatory = true, ParameterSetName = "SkipLast")]
     [Alias("LogPath")]
     public string FilePath { get; set; } = string.Empty;
 
+    /// <summary>
+    /// Gets or sets the number of records to take from the start of the log.
+    /// </summary>
     [Parameter(ParameterSetName = "FirstLastSkip")]
     public int? First { get; set; }
 
+    /// <summary>
+    /// Gets or sets the number of records to take from the end of the log.
+    /// </summary>
     [Parameter(ParameterSetName = "FirstLastSkip")]
     public int? Last { get; set; }
 
+    /// <summary>
+    /// Gets or sets the number of records to skip from the start of the log.
+    /// </summary>
     [Parameter(ParameterSetName = "FirstLastSkip")]
     public int? Skip { get; set; }
 
+    /// <summary>
+    /// Gets or sets the number of records to skip from the end of the log.
+    /// </summary>
     [Parameter(ParameterSetName = "SkipLast")]
     public int? SkipLast { get; set; }
 
+    /// <inheritdoc />
     protected override Task BeginProcessingAsync() {
         ActionPreference pref = GetErrorActionPreference();
         if (EnsureFileExists(FilePath, pref)) {
@@ -37,6 +56,7 @@ protected override Task BeginProcessingAsync() {
         return Task.CompletedTask;
     }
 
+    /// <inheritdoc />
     protected override Task ProcessRecordAsync() {
         if (_parser == null) {
             return Task.CompletedTask;
@@ -66,6 +86,7 @@ protected override Task ProcessRecordAsync() {
         return Task.CompletedTask;
     }
 
+    /// <inheritdoc />
     protected override Task EndProcessingAsync() {
         _parser?.Dispose();
         return Task.CompletedTask;

IISParser/IISLogEvent.cs

@@ -3,27 +3,117 @@
 
 namespace IISParser;
 
+/// <summary>
+/// Represents a single entry in an IIS log file.
+/// </summary>
 public class IISLogEvent {
+    /// <summary>
+    /// Gets or sets the timestamp of the log entry.
+    /// </summary>
     public DateTime DateTimeEvent { get; set; }
+
+    /// <summary>
+    /// Gets or sets the site name reported by the server (<c>s-sitename</c>).
+    /// </summary>
     public string? sSitename { get; set; }
+
+    /// <summary>
+    /// Gets or sets the computer name for the server (<c>s-computername</c>).
+    /// </summary>
     public string? sComputername { get; set; }
+
+    /// <summary>
+    /// Gets or sets the server IP address (<c>s-ip</c>).
+    /// </summary>
     public string? sIp { get; set; }
+
+    /// <summary>
+    /// Gets or sets the HTTP method used by the request (<c>cs-method</c>).
+    /// </summary>
     public string? csMethod { get; set; }
+
+    /// <summary>
+    /// Gets or sets the requested resource path (<c>cs-uri-stem</c>).
+    /// </summary>
     public string? csUriStem { get; set; }
+
+    /// <summary>
+    /// Gets or sets the query portion of the requested URI (<c>cs-uri-query</c>).
+    /// </summary>
     public string? csUriQuery { get; set; }
+
+    /// <summary>
+    /// Gets or sets the server port (<c>s-port</c>).
+    /// </summary>
     public int? sPort { get; set; }
+
+    /// <summary>
+    /// Gets or sets the authenticated user name (<c>cs-username</c>).
+    /// </summary>
     public string? csUsername { get; set; }
+
+    /// <summary>
+    /// Gets or sets the client IP address (<c>c-ip</c>).
+    /// </summary>
     public string? cIp { get; set; }
+
+    /// <summary>
+    /// Gets or sets the protocol version (<c>cs-version</c>).
+    /// </summary>
     public string? csVersion { get; set; }
+
+    /// <summary>
+    /// Gets or sets the user agent string (<c>cs(User-Agent)</c>).
+    /// </summary>
     public string? csUserAgent { get; set; }
+
+    /// <summary>
+    /// Gets or sets the HTTP cookie value (<c>cs(Cookie)</c>).
+    /// </summary>
     public string? csCookie { get; set; }
+
+    /// <summary>
+    /// Gets or sets the referrer URL (<c>cs(Referer)</c>).
+    /// </summary>
     public string? csReferer { get; set; }
+
+    /// <summary>
+    /// Gets or sets the host header value (<c>cs-host</c>).
+    /// </summary>
     public string? csHost { get; set; }
+
+    /// <summary>
+    /// Gets or sets the HTTP status code (<c>sc-status</c>).
+    /// </summary>
     public int? scStatus { get; set; }
+
+    /// <summary>
+    /// Gets or sets the substatus error code (<c>sc-substatus</c>).
+    /// </summary>
     public int? scSubstatus { get; set; }
+
+    /// <summary>
+    /// Gets or sets the Windows status code (<c>sc-win32-status</c>).
+    /// </summary>
     public long? scWin32Status { get; set; }
+
+    /// <summary>
+    /// Gets or sets the number of bytes sent (<c>sc-bytes</c>).
+    /// </summary>
     public int? scBytes { get; set; }
+
+    /// <summary>
+    /// Gets or sets the number of bytes received (<c>cs-bytes</c>).
+    /// </summary>
     public int? csBytes { get; set; }
+
+    /// <summary>
+    /// Gets or sets the time taken to service the request, in milliseconds (<c>time-taken</c>).
+    /// </summary>
     public int? timeTaken { get; set; }
+
+    /// <summary>
+    /// Gets a dictionary containing all fields from the log line keyed by their original names.
+    /// </summary>
     public Dictionary<string, string?> Fields { get; } = new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
 }