Improve docs for using NLog AppCenter Target with MAUI (#38)

NLog · May 30, 2023 · 81fd3f5 · 81fd3f5
1 parent 5fa5814
commit 81fd3f5
Show file tree

Hide file tree

Showing 5 changed files with 128 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -4,40 +4,52 @@ NLog Target for [Microsoft Visual Studio App Center with Azure](https://azure.mi
 [![Version](https://badge.fury.io/nu/NLog.Targets.AppCenter.svg)](https://www.nuget.org/packages/NLog.Targets.AppCenter)
 [![AppVeyor](https://img.shields.io/appveyor/ci/nlog/nlog-azureappcenter/master.svg)](https://ci.appveyor.com/project/nlog/nlog-azureappcenter/branch/master)
 
-### How to use
+### How to setup NLog in MAUI
 
-1) Install the package
+1) Install the NLog packages
 
-    `Install-Package NLog.Targets.AppCenter` or in your csproj:
+   - `Install-Package NLog.Targets.AppCenter` 
+   - `Install-Package NLog.Extensions.Logging` 
+
+   or in your csproj:
 
     ```xml
     <PackageReference Include="NLog.Targets.AppCenter" Version="5.*" />
+    <PackageReference Include="NLog.Extensions.Logging" Version="5.*" />
     ```
 
-2) Add to your nlog.config:
+2) Add NLog to the MauiApp
 
-    ```xml
-    <extensions>
-        <add assembly="NLog.Targets.AppCenter"/>
-    </extensions>
-    ```
+   Update `MauiProgram.cs` to include NLog as Logging Provider: 
+   ```csharp
+   var builder = MauiApp.CreateBuilder();
 
-3) Use the target "appcenter" in your nlog.config
+   // Add NLog for Logging
+   builder.Logging.ClearProviders();
+   builder.Logging.AddNLog();
+   ```
 
-    ```xml
-    <targets>
-        <target name="appcenter" xsi:type="appcenter" layout="${message}" reportExceptionAsCrash="true">
-		<contextproperty name="logger" layout="${logger}" />
-		<contextproperty name="loglevel" layout="${level}" />
-		<contextproperty name="threadid" layout="${threadid}" />
-        </target>
-    </targets>
-    <rules>
-        <logger minLevel="Info" writeTo="appcenter" />
-    </rules>
-    ```
+   If getting compiler errors with unknown methods, then update `using`-section:
+   ```csharp
+   using Microsoft.Extensions.Logging;
+   using NLog;
+   using NLog.Extensions.Logging;
+   ```
+
+3) Load NLog configuration for logging
+
+   Add the `NLog.config` into the Application-project as assembly-resource (`Build Action` = `embedded resource`), and load like this:
+   ```csharp
+   NLog.LogManager.Setup().RegisterAppCenter().LoadConfigurationFromAssemblyResource(typeof(App).Assembly);
+   ```
+   Alternative setup NLog configuration using [fluent-API](https://github.com/NLog/NLog/wiki/Fluent-Configuration-API):
+   ```csharp
+   var logger = NLog.LogManager.Setup().RegisterAppCenter()
+                    .LoadConfiguration(c => c.ForLogger(NLog.LogLevel.Debug).WriteToAppCenter())
+                    .GetCurrentClassLogger();
+   ```
 
-### Configuration options for AppCenterTarget
+### Configuration options for AppCenter NLog Target
 
 - **AppSecret** - Appsecret for starting AppCenter if needed (optional)
 - **UserId** - Application UserId to register in AppCenter (optional)
@@ -47,3 +59,20 @@ NLog Target for [Microsoft Visual Studio App Center with Azure](https://azure.mi
 - **IncludeEventProperties** - Include LogEvent properties in AppCenter properties (default=true)
 - **IncludeScopeProperties** - Include MappedDiagnosticsLogicalContext (MLDC) that can be provided with MEL BeginScope (default=false)
 
+```xml
+<nlog>
+<extensions>
+    <add assembly="NLog.Targets.AppCenter"/>
+</extensions>
+<targets>
+    <target name="appcenter" xsi:type="appcenter" layout="${message}" reportExceptionAsCrash="true">
+	<contextproperty name="logger" layout="${logger}" />
+	<contextproperty name="loglevel" layout="${level}" />
+	<contextproperty name="threadid" layout="${threadid}" />
+    </target>
+</targets>
+<rules>
+    <logger minLevel="Info" writeTo="appcenter" />
+</rules>
+</nlog>
+```
diff --git a/src/NLog.Targets.AppCenter/Config/SetupBuilderExtensions.cs b/src/NLog.Targets.AppCenter/Config/SetupBuilderExtensions.cs
@@ -0,0 +1,19 @@
+using NLog.Config;
+
+namespace NLog
+{
+    /// <summary>
+    /// Extension methods to setup LogFactory options
+    /// </summary>
+    public static class SetupBuilderExtensions
+    {
+        /// <summary>
+        /// Register the NLog.Web LayoutRenderers before loading NLog config
+        /// </summary>
+        public static ISetupBuilder RegisterAppCenter(this ISetupBuilder setupBuilder)
+        {
+            setupBuilder.SetupExtensions(e => e.RegisterAppCenter());
+            return setupBuilder;
+        }
+    }
+}
diff --git a/src/NLog.Targets.AppCenter/Config/SetupExtensionsBuilderExtensions.cs b/src/NLog.Targets.AppCenter/Config/SetupExtensionsBuilderExtensions.cs
@@ -0,0 +1,19 @@
+using NLog.Config;
+using NLog.Targets;
+
+namespace NLog
+{
+    /// <summary>
+    /// Extension methods to setup NLog extensions, so they are known when loading NLog LoggingConfiguration
+    /// </summary>
+    public static class SetupExtensionsBuilderExtensions
+    {
+        /// <summary>
+        /// Register the NLog.Web LayoutRenderers
+        /// </summary>
+        public static ISetupExtensionsBuilder RegisterAppCenter(this ISetupExtensionsBuilder setupBuilder)
+        {
+            return setupBuilder.RegisterTarget<AppCenterTarget>("AppCenter");
+        }
+    }
+}
diff --git a/src/NLog.Targets.AppCenter/Config/SetupLoadConfigurationExtensions.cs b/src/NLog.Targets.AppCenter/Config/SetupLoadConfigurationExtensions.cs
@@ -0,0 +1,31 @@
+using NLog.Config;
+using NLog.Layouts;
+using NLog.Targets;
+
+namespace NLog
+{
+    /// <summary>
+    /// Extension methods to setup NLog <see cref="LoggingConfiguration"/>
+    /// </summary>
+    public static class SetupLoadConfigurationExtensions
+    {
+        /// <summary>
+        /// Write to AppCenter NLog Target
+        /// </summary>
+        /// <param name="configBuilder"></param>
+        /// <param name="layout">Override the default Layout for output</param>
+        /// <param name="appSecret">appsecret for starting AppCenter if needed</param>
+        /// <param name="reportExceptionAsCrash">activate AppCenter-Crashes and report Exceptions as crashes</param>
+        public static ISetupConfigurationTargetBuilder WriteToAppCenter(this ISetupConfigurationTargetBuilder configBuilder, Layout layout = null, Layout appSecret = null, bool reportExceptionAsCrash = false)
+        {
+            var logTarget = new AppCenterTarget();
+            if (layout != null)
+                logTarget.Layout = layout;
+            if (appSecret != null)
+                logTarget.AppSecret = appSecret;
+            if (reportExceptionAsCrash)
+                logTarget.ReportExceptionAsCrash = reportExceptionAsCrash;
+            return configBuilder.WriteTo(logTarget);
+        }
+    }
+}
diff --git a/src/NLog.Targets.AppCenter/NLog.Targets.AppCenter.csproj b/src/NLog.Targets.AppCenter/NLog.Targets.AppCenter.csproj
@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFrameworks>net462;netstandard2.0</TargetFrameworks>
-    <VersionPrefix>5.0.2</VersionPrefix>
+    <VersionPrefix>5.2.0</VersionPrefix>
     <AssemblyVersion>5.0.0.0</AssemblyVersion> <!-- Strong AssemblyVersion must be fixed on 5.0.0.0 -->
     <AppVeyorBuildNumber>$(APPVEYOR_BUILD_NUMBER)</AppVeyorBuildNumber>
     <AppVeyorBuildNumber Condition="'$(AppVeyorBuildNumber)' == ''">0</AppVeyorBuildNumber>
@@ -18,8 +18,9 @@
     <PackageIcon>N.png</PackageIcon>
     <PackageLicenseExpression>BSD-3-Clause</PackageLicenseExpression>
     <PackageReleaseNotes>
-- Updated dependency Microsoft.AppCenter to v5.0.1 - Fixed StrongName Support
-- Added StrongName Support
+- Updated dependency NLog v5.2
+- Updated dependency Microsoft.AppCenter v5.0.2
+- Added fluent API Setup() extension methods RegisterAppCenter() and WriteToAppCenter()
     </PackageReleaseNotes>
 
     <IsPackable>true</IsPackable>
@@ -33,9 +34,9 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AppCenter.Analytics" Version="5.0.1" />
-    <PackageReference Include="Microsoft.AppCenter.Crashes" Version="5.0.1" />
-    <PackageReference Include="NLog" Version="5.0.5" />
+    <PackageReference Include="Microsoft.AppCenter.Analytics" Version="5.0.2" />
+    <PackageReference Include="Microsoft.AppCenter.Crashes" Version="5.0.2" />
+    <PackageReference Include="NLog" Version="5.2.0" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="All" />
   </ItemGroup>