Logging: adding more info to README.md.

Author: gfraiteur

Diagnostics/PostSharp.Samples.Audit.Extended/ExtendedAuditRecordBuilder.cs

@@ -15,19 +15,22 @@ public ExtendedAuditRecordBuilder(AuditBackend backend) : base(backend)
     protected override AuditRecord CreateRecord(LoggingContext context, ref LogRecordInfo recordInfo,
       ref LogMemberInfo memberInfo)
     {
+      // Return an instance of our own extended class.
       return new ExtendedAuditRecord(context.Source.SourceType, memberInfo.MemberName, recordInfo.RecordKind);
     }
 
     public override void SetParameter<T>(int index, string parameterName, ParameterDirection direction, string typeName,
       T value,
       IFormatter<T> formatter)
     {
+      base.SetParameter(index, parameterName, direction, typeName, value, formatter);
+
+      // When the parameter is a business object, add it to the list of correlated business objects.      
       var businessObject = value as BusinessObject;
 
       if (businessObject != null)
         ((ExtendedAuditRecord) CurrentRecord).RelatedBusinessObjects.Add(businessObject);
 
-      base.SetParameter(index, parameterName, direction, typeName, value, formatter);
     }
   }
 }

Diagnostics/PostSharp.Samples.Audit.Extended/PurchaseOrder.cs

@@ -4,6 +4,8 @@ namespace PostSharp.Samples.Audit.Extended
 {
   public class PurchaseOrder : BusinessObject
   {
+
+    // Note the Audit aspect on this method.
     [Audit]
     public void AssignTo(Employee employee)
     {

Diagnostics/PostSharp.Samples.Audit/PurchaseOrder.cs

@@ -4,9 +4,12 @@ namespace PostSharp.Samples.Audit
 {
   public class PurchaseOrder : BusinessObject
   {
+
+    // Not the Audit aspect on this method.
     [Audit]
     public void Approve(string comment = null)
     {
+      // Details skipped.
     }
   }
 }

Diagnostics/PostSharp.Samples.Logging.CommonLogging/Program.cs

@@ -4,11 +4,12 @@
 using PostSharp.Patterns.Diagnostics.Backends.CommonLogging;
 using PostSharp.Samples.Logging.BusinessLogic;
 
+// Adds logging to all methods of this project.
 [assembly: Log]
 
 namespace PostSharp.Samples.Logging.CommonLogging
 {
-  [Log(AttributeExclude = true)]
+  [Log(AttributeExclude = true)]  // Removes logging from the Program class itself.
   internal class Program
   {
     private static void Main(string[] args)

Diagnostics/PostSharp.Samples.Logging.CommonLogging/README.md

@@ -1,6 +1,21 @@
 This example demonstrates how to configure the PostSharp Logging aspect so that it prints its output to Common.Logging.
 Here Common.Logging is configured to direct outputs to the system console.
 
+`Program.cs` is the only interesting one file. The other classes are members of the `PostSharp.Samples.Logging.BusinessLogic`
+namespace and only simulate some business logic.
+
+The `[assembly: Log]` custom attribute in `Program.cs` adds logging to the whole project. However, the `[Log(AttributeExclude = true)]`
+attribute on the `Program` class prevents the `Program` class itself from being logged. This is required because no logged
+code is allowed before the logging service is initialized.
+
+The first line of the `Program.Main` method initializes PostSharp Logging. The method then executes the business code to produce some
+output in the log.
+
+## Viewing the log
+
+In this example, the log is only printed to the console. No file is created.
+
+
 ## Documentation
 
 [Logging to the Common.Logging](http://doc.postsharp.net/common-logging)

Diagnostics/PostSharp.Samples.Logging.Console/Program.cs

@@ -2,11 +2,12 @@
 using PostSharp.Patterns.Diagnostics.Backends.Console;
 using PostSharp.Samples.Logging.BusinessLogic;
 
+// Add logging to all methods of the current project.
 [assembly: Log]
 
 namespace PostSharp.Samples.Logging.Console
 {
-  [Log(AttributeExclude = true)]
+  [Log(AttributeExclude = true)]   // Removes logging from the Program class itself.
   internal class Program
   {
     private static void Main(string[] args)

Diagnostics/PostSharp.Samples.Logging.Console/README.md

@@ -1,5 +1,19 @@
 This example demonstrates how to configure the PostSharp Logging aspect so that it prints its output to the system console.
 
+`Program.cs` is the only interesting one file. The other classes are members of the `PostSharp.Samples.Logging.BusinessLogic`
+namespace and only simulate some business logic.
+
+The `[assembly: Log]` custom attribute in `Program.cs` adds logging to the whole project. However, the `[Log(AttributeExclude = true)]`
+attribute on the `Program` class prevents the `Program` class itself from being logged. This is required because no logged
+code is allowed before the logging service is initialized.
+
+The first line of the `Program.Main` method initializes PostSharp Logging. The method then executes the business code to produce some
+output in the log.
+
+## Viewing the log
+
+In this example, the log is only printed to the console. No file is created.
+
 
 ## Documentation
 

Diagnostics/PostSharp.Samples.Logging.CustomBackend.ServiceStack/Program.cs

@@ -2,7 +2,10 @@
 using PostSharp.Samples.Logging.BusinessLogic;
 using ServiceStack.Logging;
 
+// Add logging to all methods of this project.
 [assembly: Log(AttributePriority = 0)]
+
+// Exclude logging from the PostSharp.Samples.Logging.CustomBackend.ServiceStack namespace.
 [assembly:
   Log(AttributePriority = 1, AttributeExclude = true,
     AttributeTargetTypes = "PostSharp.Samples.Logging.CustomBackend.ServiceStack.*")]

Diagnostics/PostSharp.Samples.Logging.Etw/Program.cs

@@ -2,11 +2,12 @@
 using PostSharp.Patterns.Diagnostics.Backends.EventSource;
 using PostSharp.Samples.Logging.BusinessLogic;
 
+// Add logging to all methods of this project.
 [assembly: Log]
 
 namespace PostSharp.Samples.Logging.Etw
 {
-  [Log(AttributeExclude = true)]
+  [Log(AttributeExclude = true)]   // Removes logging from the Program class itself.
   internal class Program
   {
     private static void Main(string[] args)

Diagnostics/PostSharp.Samples.Logging.Etw/README.md

@@ -1,5 +1,27 @@
 This example demonstrates how to configure the PostSharp Logging aspect so that it prints its output to ETW.
 
+`Program.cs` is the only interesting one file. The other classes are members of the `PostSharp.Samples.Logging.BusinessLogic`
+namespace and only simulate some business logic.
+
+The `[assembly: Log]` custom attribute in `Program.cs` adds logging to the whole project. However, the `[Log(AttributeExclude = true)]`
+attribute on the `Program` class prevents the `Program` class itself from being logged. This is required because no logged
+code is allowed before the logging service is initialized.
+
+The first line of the `Program.Main` method initializes PostSharp Logging. The method then executes the business code to produce some
+output in the log.
+
+## Viewing the log
+
+To view the log produced by this example, you need to attach a log collector:
+
+1. Download PerfView from https://www.microsoft.com/en-us/download/details.aspx?id=28567.
+
+2. Execute: perfview.exe collect -OnlyProviders *PostSharp-Patterns-Diagnostics
+
+3. Execute this program.
+
+4. In PerfView, click 'Stop collecting', then in the PerfView tree view click 'PerfViewData.etl.zip' and finally 'Events'.
+
 
 ## Documentation
 

Diagnostics/PostSharp.Samples.Logging.Log4Net/Program.cs

@@ -4,12 +4,13 @@
 using PostSharp.Patterns.Diagnostics.Backends.Log4Net;
 using PostSharp.Samples.Logging.BusinessLogic;
 
+// Add logging to all methods of this project.
 [assembly: Log]
 
 
 namespace PostSharp.Samples.Logging.Log4Net
 {
-  [Log(AttributeExclude = true)]
+  [Log(AttributeExclude = true)]   // Removes logging from the Program class itself.
   internal class Program
   {
     private static void Main(string[] args)

Diagnostics/PostSharp.Samples.Logging.Log4Net/README.md

@@ -1,6 +1,21 @@
 This example demonstrates how to configure the PostSharp Logging aspect so that it prints its output to log4net.
 
 
+`Program.cs` is the only interesting one file. The other classes are members of the `PostSharp.Samples.Logging.BusinessLogic`
+namespace and only simulate some business logic.
+
+The `[assembly: Log]` custom attribute in `Program.cs` adds logging to the whole project. However, the `[Log(AttributeExclude = true)]`
+attribute on the `Program` class prevents the `Program` class itself from being logged. This is required because no logged
+code is allowed before the logging service is initialized.
+
+The first line of the `Program.Main` method initializes PostSharp Logging. The method then executes the business code to produce some
+output in the log.
+
+## Viewing the log
+
+After you execute the file, you should find the log in the `bin\Debug` directory.
+
+
 ## Documentation
 
 [Logging to the log4net](http://doc.postsharp.net/log4net)

Diagnostics/PostSharp.Samples.Logging.Loupe/Program.cs

@@ -4,11 +4,12 @@
 using PostSharp.Patterns.Diagnostics.Backends.Loupe;
 using PostSharp.Samples.Logging.BusinessLogic;
 
+// Add logging to all methods of this project.
 [assembly: Log]
 
 namespace PostSharp.Samples.Logging.Loupe
 {
-  [Log(AttributeExclude = true)]
+  [Log(AttributeExclude = true)]   // Removes logging from the Program class itself.
   internal class Program
   {
     private static void Main(string[] args)

Diagnostics/PostSharp.Samples.Logging.Loupe/README.md

@@ -1,4 +1,18 @@
 This example demonstrates how to configure the PostSharp Logging aspect so that it prints its output to Loupe from Gibraltar.
+
+`Program.cs` is the only interesting one file. The other classes are members of the `PostSharp.Samples.Logging.BusinessLogic`
+namespace and only simulate some business logic.
+
+The `[assembly: Log]` custom attribute in `Program.cs` adds logging to the whole project. However, the `[Log(AttributeExclude = true)]`
+attribute on the `Program` class prevents the `Program` class itself from being logged. This is required because no logged
+code is allowed before the logging service is initialized.
+
+The first line of the `Program.Main` method initializes PostSharp Logging. The method then executes the business code to produce some
+output in the log.
+
+## Viewing the log
+
+
 The application automatically opens an empty window of the Loupe Viewer. You should then see a Loupe desktop notification saying that a new
 session is available. Click on this notification to open the log, and ignore the empty window that first opened.
 

Diagnostics/PostSharp.Samples.Logging.NLog/Program.cs

@@ -6,11 +6,12 @@
 using PostSharp.Samples.Logging.BusinessLogic;
 using LogLevel = NLog.LogLevel;
 
+// Add logging to all methods of this project.
 [assembly: Log]
 
 namespace PostSharp.Samples.Logging.NLog
 {
-  [Log(AttributeExclude = true)]
+  [Log(AttributeExclude = true)]   // Removes logging from the Program class itself.
   internal static class Program
   {
     private static void Main(string[] args)

Diagnostics/PostSharp.Samples.Logging.NLog/README.md

@@ -1,6 +1,21 @@
 This example demonstrates how to configure the PostSharp Logging aspect so that it prints its output to NLog.
 
 
+`Program.cs` is the only interesting one file. The other classes are members of the `PostSharp.Samples.Logging.BusinessLogic`
+namespace and only simulate some business logic.
+
+The `[assembly: Log]` custom attribute in `Program.cs` adds logging to the whole project. However, the `[Log(AttributeExclude = true)]`
+attribute on the `Program` class prevents the `Program` class itself from being logged. This is required because no logged
+code is allowed before the logging service is initialized.
+
+The first line of the `Program.Main` method initializes PostSharp Logging. The method then executes the business code to produce some
+output in the log.
+
+## Viewing the log
+
+
+After you execute the file, you should find the log in the `bin\Debug` directory.
+
 ## Documentation
 
 [Logging to the log4net](http://doc.postsharp.net/nlog)

Diagnostics/PostSharp.Samples.Logging.Serilog/Program.cs

@@ -3,11 +3,12 @@
 using PostSharp.Samples.Logging.BusinessLogic;
 using Serilog;
 
+// Add logging to all methods of this project.
 [assembly: Log]
 
 namespace PostSharp.Samples.Logging.Serilog
 {
-  [Log(AttributeExclude = true)]
+  [Log(AttributeExclude = true)]   // Removes logging from the Program class itself.
   internal class Program
   {
     private static void Main(string[] args)

Diagnostics/PostSharp.Samples.Logging.Serilog/README.md

@@ -1,6 +1,21 @@
 This example demonstrates how to configure the PostSharp Logging aspect so that it prints its output to Serilog.
 
 
+`Program.cs` is the only interesting one file. The other classes are members of the `PostSharp.Samples.Logging.BusinessLogic`
+namespace and only simulate some business logic.
+
+The `[assembly: Log]` custom attribute in `Program.cs` adds logging to the whole project. However, the `[Log(AttributeExclude = true)]`
+attribute on the `Program` class prevents the `Program` class itself from being logged. This is required because no logged
+code is allowed before the logging service is initialized.
+
+The first line of the `Program.Main` method initializes PostSharp Logging. The method then executes the business code to produce some
+output in the log.
+
+## Viewing the log
+
+
+After you execute the file, you should find the log in the `bin\Debug` directory.
+
 ## Documentation
 
 [Logging to the Serilog](http://doc.postsharp.net/serilog)