Add more examples for MsBuild issue provider (#988)

Author: pascalberger

docs/input/documentation/issue-providers/msbuild/examples/index.md

@@ -0,0 +1,12 @@
+---
+title: Examples
+description: Examples for using the Cake.Issues.MsBuild addin.
+icon: material/test-tube
+---
+
+<div class="grid cards" markdown>
+
+- :material-test-tube: [Read binary log file](read-binary-log.md)
+- :material-test-tube: [Use custom URL resolver](use-custom-url-resolver.md)
+
+</div>

docs/input/documentation/issue-providers/msbuild/examples.md renamed to docs/input/documentation/issue-providers/msbuild/examples/read-binary-log.md

@@ -1,10 +1,10 @@
 ---
-title: Examples
-description: Examples for using the Cake.Issues.MsBuild addin.
+title: Read MsBuild binary log file
+description: Examples for reading a binary logfile using the Cake.Issues.MsBuild addin.
 icon: material/test-tube
 ---
 
-To read issues from MsBuild log files you need to import the MsBuild issue provider needs to be imported:
+To read issues from MsBuild log files the MsBuild issue provider needs to be imported:
 
 === "Cake .NET Tool"
 

docs/input/documentation/issue-providers/msbuild/examples/use-custom-url-resolver.md

@@ -0,0 +1,69 @@
+---
+title: Use custom URL resolver for MsBuild issues
+description: Examples for using custom URL resolver for MsBuild issues.
+icon: material/test-tube
+---
+
+!!! note
+
+    This example builds on top of the [Read binary log file](read-binary-log.md) example.
+
+The following example shows how URL schema for custom Roslyn analyzers can be defined.
+
+Before reading the issues a custom rule URL resolver can be registered to have all issues starting with `CUS` linking to an internal URL:
+
+=== "Cake .NET Tool"
+
+    ```csharp title="build.cake"
+    Task("Read-Issues")
+        .IsDependentOn("Build-Solution")
+        .Does(() =>
+        {
+            // Define custom URL resolver adding URL for all rules starting with FOO.
+            MsBuildAddRuleUrlResolver(x =>
+                x.Category.ToUpperInvariant() == "CUS" ?
+                new Uri("https://myIntranet/rules/" + x.Rule) :
+                null);
+
+            // Read issues.
+            var issues =
+                ReadIssues(
+                    MsBuildIssuesFromFilePath(
+                        logPath,
+                        MsBuildBinaryLogFileFormat),
+                    repoRootPath);
+
+            Information("{0} issues are found.", issues.Count());
+    });
+    ```
+
+=== "Cake Frosting"
+
+    ```csharp title="Program.cs"
+    using Cake.Common.Diagnostics;
+    using Cake.Frosting;
+
+    [TaskName("Read-Issues")]
+    [IsDependentOn(typeof(BuildSolutionTask))]
+    public sealed class ReadIssuesTask : FrostingTask<BuildContext>
+    {
+        public override void Run(BuildContext context)
+        {
+            // Define custom URL resolver adding URL for all rules starting with FOO.
+            context.MsBuildAddRuleUrlResolver(x =>
+                x.Category.ToUpperInvariant() == "CUS" ?
+                new Uri("https://myIntranet/rules/" + x.Rule) :
+                null);
+
+            // Read issues.
+            var issues =
+                context.ReadIssues(
+                    context.MsBuildIssuesFromFilePath(
+                        context.LogPath,
+                        context.MsBuildBinaryLogFileFormat()),
+                    context.RepoRootPath);
+
+            context.Information("{0} issues are found.", issues.Count());
+        }
+    }
+    ```

docs/input/documentation/issue-providers/msbuild/index.md

@@ -9,7 +9,7 @@ Support for reading warnings reported by MsBuild is implemented in the
 <div class="grid cards" markdown>
 
 - :material-creation-outline: [Features](features.md)
-- :material-test-tube: [Examples](examples.md)
+- :material-test-tube: [Examples](examples/index.md)
 - :material-api: [API](https://cakebuild.net/extensions/cake-issues-msbuild){target="_blank"}
 
 </div>

docs/mkdocs.yml

@@ -201,7 +201,10 @@ nav:
         - MsBuild:
           - documentation/issue-providers/msbuild/index.md
           - Features: documentation/issue-providers/msbuild/features.md
-          - Examples: documentation/issue-providers/msbuild/examples.md
+          - Examples:
+            - documentation/issue-providers/msbuild/examples/index.md
+            - Read binary log file: documentation/issue-providers/msbuild/examples/read-binary-log.md
+            - Use custom URL resolver: documentation/issue-providers/msbuild/examples/use-custom-url-resolver.md
           - API: https://cakebuild.net/extensions/cake-issues-msbuild" target="_blank
         - Sarif:
           - documentation/issue-providers/sarif/index.md