jj: update docs

Modules.Logging/LogConfig.vb

@@ -8,13 +8,18 @@ Imports NLog.Targets
 ''' 
 ''' VERSION:        0.0.0.1
 ''' 
-''' DATE:           20.08.2018
+''' DATE:           24.08.2018
 ''' 
 ''' DESCRIPTION:    Module that writes file-logs to different locations:
 '''                 local application data, the current directory or a custom path.
 '''                 Files and directories will be automatically created.
 '''                 
-'''                 Three different logfiles will be generated
+'''                 Three different logfiles will be generated:
+'''                 
+'''                 - Default: Warn, Error and Fatal Log Levels
+'''                 - Detail: Info Log Level
+'''                 - Debug: Debug Log Level
+'''                   
 ''' 
 ''' DEPENDENCIES:   NLog, >= 4.5.8
 ''' 
@@ -32,16 +37,51 @@ Imports NLog.Targets
 '''                 If set to anything other than Nothing, extends the logfile name with this suffix.
 '''             
 ''' PROPERTIES:     LogFile, String (readonly)
-'''                 Contains the full path of the default log file.
+'''                 Returns the full path of the default log file.
 ''' 
 '''                 LogPath, String (readonly)
-'''                 Contains the path to the log directory.                
+'''                 Returns the path to the log directory.
+'''                 
+'''                 LogFactory, NLog.LogFactory (readonly)
+'''                 Returns the LogFactory that is used to create the Logger object
 ''' 
 '''                 Debug, Boolean
 '''                 Determines if the debug log should be written.
 '''                 
+''' EXAMPLES:       Class FooProgram
+'''                     Private Logger as NLog.Logger
+'''                     Private LogConfig as DigitalData.Modules.Logging.LogConfig
+'''                 
+'''                     Public Sub New(LogFactory as NLog.LogFactory)
+'''                         LogConfig = new DigitalData.Modules.Logging.LogConfig(args)
+'''                         Logger = LogConfig.LogFactory.GetCurrentClassLogger()
+'''                     End Sub
+'''                     
+'''                     Public Sub Bar()
+'''                         Logger.Info("Baz")
+'''                     End Sub
+'''                 End Class
+'''                 
+'''                 Class FooLib
+'''                     Private Logger as NLog.Logger
+'''                 
+'''                     Public Sub New(LogFactory as NLog.LogFactory)
+'''                         Logger = LogFactory.GetCurrentClassLogger()
+'''                     End Sub
+'''                     
+'''                     Public Sub Bar()
+'''                         Logger.Info("Baz")
+'''                     End Sub
+'''                 End Class
+'''                 
 ''' REMARKS:        If logpath can not be written to, falls back to temp folder as defined in:
 '''                 https://docs.microsoft.com/de-de/dotnet/api/system.io.path.gettemppath?view=netframework-4.7.2
+'''                 
+'''                 If used in a service, LogPath must be set to CustomPath, otherwise the Log will be written to System32!
+'''                 
+'''                 For NLog Troubleshooting, set the following Environment variables to write the NLog internal Log:               
+'''                 - NLOG_INTERNAL_LOG_LEVEL: Debug
+'''                 - NLOG_INTERNAL_LOG_FILE: ex. C:\Temp\Nlog_Internal.log
 ''' </summary>
 Public Class LogConfig
     Private Const KEEP_FILES_OPEN As Boolean = False
@@ -66,13 +106,11 @@ Public Class LogConfig
     Private Const LOG_FORMAT_DEFAULT As String = LOG_FORMAT_BASE & " >> ${message}"
     Private Const LOG_FORMAT_EXCEPTION As String = LOG_FORMAT_BASE & " >> ${exception:format=Message}${newline}${exception:format=StackTrace}"
 
-    Private config As LoggingConfiguration
-    Private isDebug As Boolean = False
-
     Private ReadOnly failSafePath As String = Path.GetTempPath()
     Private ReadOnly basePath As String = failSafePath
 
-    Public ReadOnly Property LogFactory As LogFactory
+    Private config As LoggingConfiguration
+    Private isDebug As Boolean = False
 
     Public Enum PathType As Integer
         AppData = 0
@@ -80,6 +118,12 @@ Public Class LogConfig
         CustomPath = 2
     End Enum
 
+    ''' <summary>
+    ''' Returns the NLog.LogFactory object that is used to create Loggers
+    ''' </summary>
+    ''' <returns>LogFactory object</returns>
+    Public ReadOnly Property LogFactory As LogFactory
+
     ''' <summary>
     ''' Returns the path to the current default logfile
     ''' </summary>
@@ -158,6 +202,25 @@ Public Class LogConfig
         End If
 
         ' Create config object and initalize it
+        config = GetConfig(productName, logFileSuffix)
+
+        ' Save config
+        LogFactory = New LogFactory With {
+            .Configuration = config
+        }
+
+        ' Save log paths for files/directory
+        LogDirectory = basePath
+        LogFile = GetCurrentLogFilePath()
+    End Sub
+
+    ''' <summary>
+    ''' Returns the initial log configuration
+    ''' </summary>
+    ''' <param name="productName">The chosen productname</param>
+    ''' <param name="logFileSuffix">The chosen suffix</param>
+    ''' <returns>A NLog.LoggingConfiguration object</returns>
+    Private Function GetConfig(productName As String, logFileSuffix As String) As LoggingConfiguration
         config = New LoggingConfiguration()
         config.Variables("product") = productName
         config.Variables("suffix") = logFileSuffix
@@ -174,18 +237,8 @@ Public Class LogConfig
         config.AddRuleForOneLevel(LogLevel.Warn, TARGET_DEFAULT)
         config.AddRuleForOneLevel(LogLevel.Info, TARGET_DETAIL)
 
-        ' Save config
+        Return config
-        LogFactory = New LogFactory With {
+    End Function
-            .Configuration = config
-        }
-        'LogManager.Configuration = config
-
-        ' Save log paths for files/directory
-        LogDirectory = basePath
-        LogFile = GetCurrentLogFilePath()
-    End Sub
-
-
 
     ''' <summary>
     ''' Returns the full path of the current default log file.
@@ -207,12 +260,13 @@ Public Class LogConfig
         ' Clear Logging Rules
         config.LoggingRules.Clear()
 
-        ' Add default targets and debug target
+        ' Add default targets
         config.AddRuleForOneLevel(LogLevel.Error, TARGET_DEFAULT_EX)
         config.AddRuleForOneLevel(LogLevel.Fatal, TARGET_DEFAULT_EX)
         config.AddRuleForOneLevel(LogLevel.Warn, TARGET_DEFAULT)
         config.AddRuleForOneLevel(LogLevel.Info, TARGET_DETAIL)
 
+        ' Add debug target, if configured
         If Debug Then
             config.AddRuleForOneLevel(LogLevel.Debug, TARGET_DEBUG)
         End If