About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers  Aliases  Modules
 

about_PowerShellLogging

Powershelllogging

PowerShellLogging
 

SHORT DESCRIPTION

    Provides background information about the PowerShellLogging module. 
     

LONG DESCRIPTION

    This topic provides information about the PowerShellLogging.IHostIoSubscriber 
    interface, the PowerShellLogging.LogFile and PowerShellLogging.ScriptBlockOutputSubscriber 
    classes that implement it, and the Windows PowerShell cmdlets used to 
    manage objects of these types. 
     
  About PowerShellLogging 
      The PowerShellLogging module helps to solve the problem of how to capture 
      all output host, and tee it to a log file (including Error, Warning, 
      Verbose, and Debug streams), without relying on the user who called 
      a script to redirect those streams to a log file, and without relying 
      on calls to specific cmdlets or functions.  An existing PowerShell 
      script can achieve full logging by importing this module and executing 
      the Enable-LogFile cmdlet. 
       
      It accomplishes this by using .NET Reflection to access private members 
      of the PowerShell classes.  This is a double-edged sword, as any time 
      Microsoft releases a new version of PowerShell (or even a patch to the 
      existing version), this module's functionality may break and require an 
      update.  If you prefer not to use this approach, there is a script-based 
      module with similar (though less complete) functionality available at 
      http://gallery.technet.microsoft.com/scriptcenter/Write-timestamped-output-4ff1565f 
     
  PowerShellLogging.HostIoInterceptor and PowerShellLogging.IHostIoSubscriber 
      The heart of this module is the HostIoInterceptor class, which is a subclass 
      of Microsoft's System.Management.Automation.Host.PSHostUserInterface class 
      and acts as a middle man between the InternalHostUserInterface class and its 
      externalUI field.  Every time the PowerShell host sends text output to the 
      console or ISE output window, it does so via calls to the externalUI field. 
       
      This module replaces the externalUI field with an instace of the 
      HostIoInterceptor object.  HostIoInterceptor passes calls on to the original 
      externalUI object, and also to any number of objects implementing the 
      PowerShellLogging.IHostIoSubscriber interface, with one minor difference: when passing 
      output to the subscribers, it is broken up into lines, and the strings sent 
      to the subscriber include the trailing carriage return/newline characters. 
       
      The module provides two classes that implement IHostIoSubscriber out of the 
      box: PowerShellLogging.LogFile and PowerShellLogging.ScriptBlockOutputSubscriber.  Both of 
      these classes focus only on host Output (Output, Error, Warning, Verbose and 
      Debug streams).  The LogFile class has certain hard-coded behavior that I 
      desire on my own scripts and log files: it prepends each non-blank line of 
      output with a date/time string (in a culture-invariant format to avoid confusion 
      over time zones or date formats).  The ScriptBlockOutputSubscriber class exists 
      to provide a dynamic alternative for people who might not want the same logging 
      behavior that I use; it simply executes script blocks for each type of output, 
      and allows the script writer to decide what to do with the text. 
       
      Please note that this is very low-level interception of text, after PowerShell's 
      formatting cmdlets have already processed the objects in the pipeline.  You cannot 
      intercept an ErrorRecord object via the HostInterceptor, for example; you can only 
      intercept the several lines of text that are displayed when an ErrorRecord object 
      is displayed in the console.  This works very well when creating text-based log files, 
      but will be of little use if you want to add an Event Log entry or database record 
      for an entire error record. 
       
  PowerShellLogging Cmdlets 
  
      When the PowerShellLogging module is loaded, the following Cmdlets are available: 
      
          Cmdlet                     Descriptions 
          ---------                  -------------------------------- 
          Enable-LogFile             Creates or attaches a LogFile to the interceptor. 
          Get-LogFile                Retrieves references to attached LogFile objects. 
          Disable-LogFile            Detaches a LogFile object from the interceptor. 
          Enable-OutputSubscriber    Creates or attaches a ScriptBlockOutputSubscriber. 
          Get-OutputSubscriber       Retrieves references to attached ScriptBlockOutputSubscribers. 
          Disable-OutputSubscriber   Detaches a ScriptBlockOutputSubscriber. 
          Suspend-Logging            Temporarily stops the interceptor from making calls to subscribers. 
          Resume-Logging             Resumes interceptor-to-subscriber calls. 
  
  Notes 
      When creating new references to LogFile or OutputSubscriber objects, the calling script 
      must maintain a reference to the resulting objects for as long as they intend the subscriber 
      to remain active.  As soon as the script releases the reference (either intentionally, or 
      due to the variable falling out of scope), the subscriber object becomes eligible for garbage 
      collection, and will be detached within a short time. 
       
      This is to make sure that subscribers don't remain active for an entire PowerShell session 
      by mistake, if a script author forgets to call Disable-LogFile / Disable-OutputSubscriber, 
      or if the script crashes before that cleanup code can be called.  It is still possible for 
      such objects to remain active after a script ends, if the script author chooses to place 
      those variables in the Global scope. 
       
      This logging technique creates certain "circular reference" style situations which may 
      cause infinite output to either the console, or worse, to a log file.  For example, 
      creating a LogFile object and then executing Get-Content on its file (allowing the output 
      of Get-Content to be displayed to the screen) will run forever until either cancelled, 
      or until it errors out for some reason (probably because you've just filled your hard disk). 
       
      To be on the safe side, I'd recommend not attempting to read the log file at all until 
      after you've called Disable-LogFile. 
       
      If, for some reason, you need to perform an action like this, that's what the Suspend-Logging 
      and Resume-Logging Cmdlets are for. 
 

SEE ALSO

Enable-LogFile
Get-LogFile
Disable-LogFile
Enable-OutputSubscriber
Get-OutputSubscriber
Disable-OutputSubscriber
Suspend-Logging
Resume-Logging