FreeLog

1.0.0

en-US/FreeLog/FreeLog-Help.xml

                                <?xml version="1.0" encoding="utf-8"?>

<helpItems xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" schema="maml" xmlns="http://msh">

  <command:command>

    <command:details>

      <command:name>New-LogFile</command:name>

      <maml:description>

        <maml:para>Creates and initializes a new global log file instance.</maml:para>

      </maml:description>

      <command:verb>New</command:verb>

      <command:noun>LogFile</command:noun>

    </command:details>

    <maml:description>

      <maml:para>The New-LogFile function creates a new FreeLogClass instance and stores it in the script-scoped $logger variable for global access throughout your script or module. It automatically creates the physical log file if it doesn't exist.</maml:para>

      <maml:para>This function is the required initialization step before using Write-LogFile.</maml:para>

    </maml:description>

    <command:syntax>

      <command:syntaxItem>

        <maml:name>New-LogFile</maml:name>

        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">

          <maml:name>Confirm</maml:name>

          <maml:description>

            <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>

          </maml:description>

          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>

        </command:parameter>

        <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">

          <maml:name>Path</maml:name>

          <maml:description>

            <maml:para>The full file system path where the log file should be created or accessed.

This parameter is

mandatory and must be a valid file path.

The function will create any missing directories in

the path structure automatically.</maml:para>

          </maml:description>

          <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>

        </command:parameter>

        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">

          <maml:name>WhatIf</maml:name>

          <maml:description>

            <maml:para>Runs the command in a mode that only reports what would happen without performing the actions.</maml:para>

          </maml:description>

          <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>

        </command:parameter>

      </command:syntaxItem>

    </command:syntax>

    <command:parameters>

      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">

        <maml:name>Confirm</maml:name>

        <maml:description>

          <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>

        </maml:description>

        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>

      </command:parameter>

      <command:parameter required="true" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">

        <maml:name>Path</maml:name>

        <maml:description>

          <maml:para>The full file system path where the log file should be created or accessed.

This parameter is

mandatory and must be a valid file path.

The function will create any missing directories in

the path structure automatically.</maml:para>

        </maml:description>

        <command:parameterValue required="true" variableLength="true">System.String</command:parameterValue>

      </command:parameter>

      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="Named" aliases="none">

        <maml:name>WhatIf</maml:name>

        <maml:description>

          <maml:para>Runs the command in a mode that only reports what would happen without performing the actions.</maml:para>

        </maml:description>

        <command:parameterValue required="false" variableLength="true">System.Management.Automation.SwitchParameter</command:parameterValue>

      </command:parameter>

    </command:parameters>

    <command:inputTypes>

      <command:inputType>

        <dev:type>

          <dev:name>None. This function does not accept pipeline input.</dev:name>

        </dev:type>

        <maml:description>

          <maml:para>{{ Fill in the Description }}</maml:para>

        </maml:description>

      </command:inputType>

    </command:inputTypes>

    <command:returnValues>

      <command:returnValue>

        <dev:type>

          <dev:name>None. The function creates a script-scoped logger variable but does not return any output.</dev:name>

        </dev:type>

        <maml:description>

          <maml:para>{{ Fill in the Description }}</maml:para>

        </maml:description>

      </command:returnValue>

    </command:returnValues>

    <maml:alertSet>

      <maml:alert>

        <maml:para>Function Name : New-LogFile

Requires      : PowerShell 5.0 or later (for class support)

Dependencies  : FreeLogClass

Scope         : Creates/updates $script:logger variable

Module        : FreeLog</maml:para>

      </maml:alert>

    </maml:alertSet>

    <command:examples>

      <command:example>

        <maml:title>--------- EXAMPLE 1 ---------</maml:title>

        <maml:introduction>

          <maml:para># Basic log file creation

New-LogFile -Path "C:\Logs\application.log"</maml:para>

          <maml:para>&#x80;</maml:para>

          <maml:para>Creates a new log file instance at the specified path and initializes the global logger.</maml:para>

        </maml:introduction>

        <dev:code />

        <dev:remarks />

      </command:example>

      <command:example>

        <maml:title>--------- EXAMPLE 2 ---------</maml:title>

        <maml:introduction>

          <maml:para>New-LogFile -Path "C:\Logs\app.log"

Write-LogFile -TaskMessage "Application started"

Write-LogFile -TaskWarn "Configuration file not found, using defaults"</maml:para>

        </maml:introduction>

        <dev:code />

        <dev:remarks />

      </command:example>

    </command:examples>

    <command:relatedLinks>

      <maml:navigationLink>

        <maml:linkText>Online Version</maml:linkText>

        <command:uri />

      </maml:navigationLink>

    </command:relatedLinks>

  </command:command>

  <command:command>

    <command:details>

      <command:name>Write-LogFile</command:name>

      <maml:description>

        <maml:para>Writes messages to the active log file using different severity levels.</maml:para>

      </maml:description>

      <command:verb>Write</command:verb>

      <command:noun>LogFile</command:noun>

    </command:details>

    <maml:description>

      <maml:para>The Write-LogFile function provides an interface for logging messages. It supports four distinct logging levels and automatically routes messages to the appropriate logger method.</maml:para>

    </maml:description>

    <command:syntax>

      <command:syntaxItem>

        <maml:name>Write-LogFile</maml:name>

        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none">

          <maml:name>TaskError</maml:name>

          <maml:description>

            <maml:para>Specifies an error message to log.</maml:para>

          </maml:description>

          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

        </command:parameter>

        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none">

          <maml:name>TaskFail</maml:name>

          <maml:description>

            <maml:para>Specifies a critical failure message to log.</maml:para>

          </maml:description>

          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

        </command:parameter>

        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">

          <maml:name>TaskMessage</maml:name>

          <maml:description>

            <maml:para>Specifies a standard informational message to log.</maml:para>

          </maml:description>

          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

        </command:parameter>

        <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">

          <maml:name>TaskWarn</maml:name>

          <maml:description>

            <maml:para>Specifies a warning message to log.</maml:para>

          </maml:description>

          <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

        </command:parameter>

      </command:syntaxItem>

    </command:syntax>

    <command:parameters>

      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="2" aliases="none">

        <maml:name>TaskError</maml:name>

        <maml:description>

          <maml:para>Specifies an error message to log.</maml:para>

        </maml:description>

        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

      </command:parameter>

      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="3" aliases="none">

        <maml:name>TaskFail</maml:name>

        <maml:description>

          <maml:para>Specifies a critical failure message to log.</maml:para>

        </maml:description>

        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

      </command:parameter>

      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="0" aliases="none">

        <maml:name>TaskMessage</maml:name>

        <maml:description>

          <maml:para>Specifies a standard informational message to log.</maml:para>

        </maml:description>

        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

      </command:parameter>

      <command:parameter required="false" variableLength="false" globbing="false" pipelineInput="false" position="1" aliases="none">

        <maml:name>TaskWarn</maml:name>

        <maml:description>

          <maml:para>Specifies a warning message to log.</maml:para>

        </maml:description>

        <command:parameterValue required="false" variableLength="true">System.String</command:parameterValue>

      </command:parameter>

    </command:parameters>

    <command:inputTypes>

      <command:inputType>

        <dev:type>

          <dev:name>System.String</dev:name>

        </dev:type>

        <maml:description>

          <maml:para>You can pipe strings to any of the four message parameters using property names that

match the parameter names (TaskMessage, TaskWarn, TaskError, TaskFail).</maml:para>

        </maml:description>

      </command:inputType>

    </command:inputTypes>

    <command:returnValues>

      <command:returnValue>

        <dev:type>

          <dev:name>System.String</dev:name>

        </dev:type>

        <maml:description>

          <maml:para>The function outputs a formatted string showing the log type and message that was logged.</maml:para>

        </maml:description>

      </command:returnValue>

    </command:returnValues>

    <maml:alertSet>

      <maml:alert>

        <maml:para>Function Name : Write-LogFile

Requires      : PowerShell 5.0 or later

Dependencies  : FreeLogClass, New-LogFile function

Scope         : Depends on script-scoped $logger variable

Module        : FreeLog

Example Pipeline Integration:

    Get-Process | ForEach-Object {

        [PSCustomObject]@{

            TaskMessage = "Process $($_.Name) running with ID $($_.Id)"

        }

    } |  Write-LogFile</maml:para>

      </maml:alert>

    </maml:alertSet>

    <command:examples>

      <command:example>

        <maml:title>--------- EXAMPLE 1 ---------</maml:title>

        <maml:introduction>

          <maml:para># Initialize logger first

New-LogFile -Path "C:\Logs\app.log"</maml:para>

        </maml:introduction>

        <dev:code />

        <dev:remarks />

      </command:example>

      <command:example>

        <maml:title>--------- EXAMPLE 2 ---------</maml:title>

        <maml:introduction>

          <maml:para># Pipeline usage with custom objects

$tasks = @(

    [PSCustomObject]@{TaskMessage = "Step 1 completed"},

    [PSCustomObject]@{TaskWarn = "Step 2 completed with warnings"},

    [PSCustomObject]@{TaskError = "Step 3 failed"}

)

$tasks | Write-LogFile</maml:para>

        </maml:introduction>

        <dev:code />

        <dev:remarks />

      </command:example>

      <command:example>

        <maml:title>--------- EXAMPLE 3 ---------</maml:title>

        <maml:introduction>

          <maml:para># Capture output for further processing

$result = Write-LogFile -TaskMessage "User login successful"

$result  # Outputs: "LOG: User login successful"</maml:para>

        </maml:introduction>

        <dev:code />

        <dev:remarks />

      </command:example>

      <command:example>

        <maml:title>--------- EXAMPLE 4 ---------</maml:title>

        <maml:introduction>

          <maml:para># Error handling when logger not initialized

try {

    Write-LogFile -TaskMessage "Test message"

}

catch {

    Write-Error "Logging failed: $_"  # Throws if New-LogFile hasn't been called

}</maml:para>

        </maml:introduction>

        <dev:code />

        <dev:remarks />

      </command:example>

    </command:examples>

    <command:relatedLinks>

      <maml:navigationLink>

        <maml:linkText>Online Version</maml:linkText>

        <command:uri />

      </maml:navigationLink>

    </command:relatedLinks>

  </command:command>

</helpItems></command:example>

    </command:examples>

    <command:relatedLinks>

      <maml:navigationLink>

        <maml:linkText>Online Version</maml:linkText>

        <command:uri />

      </maml:navigationLink>

    </command:relatedLinks>

  </command:command>

</helpItems>