Update examples (#874)

cake-contrib · Dec 30, 2024 · 3a24296 · 3a24296
1 parent 6894103
commit 3a24296
Show file tree

Hide file tree

Showing 13 changed files with 84 additions and 150 deletions.
diff --git a/docs/docs/documentation/issue-providers/msbuild/examples.md b/docs/docs/documentation/issue-providers/msbuild/examples.md
@@ -13,43 +13,39 @@ To read issues from MsBuild log files you need to import the core addin and the
 #addin nuget:?package=Cake.Issues.MsBuild&version={{ cake_issues_version }}
 ```
 
-In this example the log file is written by the `XmlFileLogger` class from [MSBuild Extension Pack].
-In order to use the above logger, the following line will download and install the tool from NuGet.org:
-
-```csharp
-#tool "nuget:?package=MSBuild.Extension.Pack" // (1)!
-```
-
---8<-- "snippets/pinning.md"
-
 We need some global variables:
 
 ```csharp
 var logPath = @"c:\build\msbuild.log";
 var repoRootPath = @"c:\repo";
 ```
 
-The following task will build the solution and write a log file:
+The following task will build the solution and write a binary log file:
 
 ```csharp
 Task("Build-Solution").Does(() =>
 {
-    // Build solution.
-    var settings =
-        new MSBuildSettings()
-            .WithLogger(
-                Context.Tools.Resolve("MSBuild.ExtensionPack.Loggers.dll").FullPath,
-                "XmlFileLogger",
-                $"logfile=\"{logPath}\";verbosity=Detailed;encoding=UTF-8"
-    );
-
-    MSBuild(repoRootPath.CombineWithFilePath("MySolution.sln"), settings);
+    var msBuildSettings =
+        new MSBuildSettings().WithLogger(
+            "BinaryLogger," + Context.Tools.Resolve("Cake.Issues.MsBuild*/**/StructuredLogger.dll"),
+            "",
+            logPath)
+    DotNetBuild(
+        repoRootPath.CombineWithFilePath("MySolution.sln"),
+        new DotNetBuildSettings{MSBuildSettings = msBuildSettings});
 });
 ```
 
+!!! Tip
+    When using `MSBuildSettings.BinaryLogger` property to write a binary log, the version of the binary log format written
+    depends on the version of the .NET SDK.
+
+    To avoid the risk of breaking builds when the .NET SDK is updated and introduces a new binary log format, which is not supported
+    in the used version of Cake.Issues.MsBuild, the binary logger instance shipped as part of Cake.Issues.MsBuild is
+    used in the above example.
+
 Finally you can define a task where you call the core addin with the desired issue provider.
-The following example reads issues reported as MsBuild warnings by the `XmlFileLogger`
-class from [MSBuild Extension Pack]:
+The following example reads warnings and errors reported as MsBuild in a binary log:
 
 ```csharp
 Task("Read-Issues")
@@ -61,11 +57,9 @@ Task("Read-Issues")
             ReadIssues(
                 MsBuildIssuesFromFilePath(
                     logPath,
-                    MsBuildXmlFileLoggerFormat),
+                    MsBuildBinaryLogFileFormat),
                 repoRootFolder);
 
         Information("{0} issues are found.", issues.Count());
     });
 ```
-
-[MSBuild Extension Pack]: https://github.com/mikefourie-zz/MSBuildExtensionPack
diff --git a/...ocs/documentation/pull-request-systems/azure-devops/examples/azure-pipelines.md b/...ocs/documentation/pull-request-systems/azure-devops/examples/azure-pipelines.md
@@ -19,10 +19,19 @@ in this example for JetBrains InspectCode:
 
 --8<-- "snippets/pinning.md"
 
-In the following task we'll first determine if the build is running on Azure DevOps and for a pull request,
-then read the remote repository URL and pull request id from environment variables set by the Azure Pipelines build
-and finally call the [AzureDevOpsPullRequests](https://cakebuild.net/api/Cake.Issues.PullRequests.AzureDevOps/AzureDevOpsPullRequestSystemAliases/){target="_blank"}
-alias using the OAuth token provided by the Azure Pipeline build.
+The following task will call the [AzureDevOpsPullRequests](https://cakebuild.net/api/Cake.Issues.PullRequests.AzureDevOps/AzureDevOpsPullRequestSystemAliases/){target="_blank"}
+alias to connect to the pull request using the environment variables provided by Azure Pipelines.
+
+```csharp
+Task("ReportIssuesToPullRequest").Does(() =>
+{
+    ReportIssuesToPullRequest(
+        InspectCodeIssuesFromFilePath(
+            @"C:\build\inspectcode.log"),
+        AzureDevOpsPullRequests(),
+        repoRootFolder);
+});
+```
 
 !!! info
     Please note that you'll need to setup your Azure Pipelines build to
@@ -31,47 +40,4 @@ alias using the OAuth token provided by the Azure Pipeline build.
 
     See [OAuth authentication from Azure Pipelines] for details.
 
-```csharp
-Task("ReportIssuesToPullRequest").Does(() =>
-{
-    var isRunningOnAzureDevOps =
-        !string.IsNullOrWhiteSpace(context.EnvironmentVariable("TF_BUILD")) &&
-        !string.IsNullOrWhiteSpace(context.EnvironmentVariable("SYSTEM_COLLECTIONURI")) &&
-        (
-            new Uri(context.EnvironmentVariable("SYSTEM_COLLECTIONURI")).Host == "dev.azure.com" ||
-            new Uri(context.EnvironmentVariable("SYSTEM_COLLECTIONURI")).Host.EndsWith("visualstudio.com")
-        );
-
-    var isPullRequestBuild =
-        !string.IsNullOrWhiteSpace(context.EnvironmentVariable("SYSTEM_PULLREQUEST_PULLREQUESTID"));
-
-    if (isRunningOnAzureDevOps)
-        {
-            var repositoryUrl = new Uri(context.EnvironmentVariable("BUILD_REPOSITORY_URI"));
-
-            if (isPullRequestBuild)
-            {
-                var pullRequestIdVariable = context.EnvironmentVariable("SYSTEM_PULLREQUEST_PULLREQUESTID");
-                if (!Int32.TryParse(pullRequestIdVariable, out var pullRequestId))
-                {
-                    throw new Exception($"Invalid pull request ID: {pullRequestIdVariable}");
-                }
-                else
-                {
-                    var repoRootFolder = MakeAbsolute(Directory("./"));
-
-                    ReportIssuesToPullRequest(
-                        InspectCodeIssuesFromFilePath(
-                            @"C:\build\inspectcode.log"),
-                        AzureDevOpsPullRequests(
-                            repositoryUrl,
-                            pullRequestId,
-                            AzureDevOpsAuthenticationOAuth(EnvironmentVariable("SYSTEM_ACCESSTOKEN"))),
-                        repoRootFolder);
-                }
-            }
-        }
-});
-```
-
 [OAuth authentication from Azure Pipelines]: ../setup.md#oauth-authentication-from-azure-pipelines
diff --git a/docs/docs/documentation/report-formats/console/examples.md b/docs/docs/documentation/report-formats/console/examples.md
@@ -7,7 +7,6 @@ icon: material/test-tube
 The following example will print issues logged as warnings by MsBuild to the console.
 
 ```csharp
-#tool "nuget:?package=MSBuild.Extension.Pack" // (1)!
 #addin nuget:?package=Cake.Issues&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.MsBuild&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.Reporting&version={{ cake_issues_version }}
@@ -17,26 +16,24 @@ Task("Create-IssueReport").Does(() =>
 {
     var repoRootFolder = new DirectoryPath(@"c:\repo");
 
-    // Build MySolution.sln solution in the repository root folder and log issues
-    // using XmlFileLogger from MSBuild Extension Pack.
+    // Build MySolution.sln solution in the repository root folder and write a binary log.
     FilePath msBuildLogFile = @"c:\build\msbuild.log";
-    var settings = new MsBuildSettings()
-        .WithLogger(
-            Context.Tools.Resolve("MSBuild.ExtensionPack.Loggers.dll").FullPath,
-            "XmlFileLogger",
-            string.Format(
-                "logfile=\"{0}\";verbosity=Detailed;encoding=UTF-8",
-                msBuildLogFile)
-        );
-    MSBuild(repoRootFolder.CombineWithFilePath("MySolution.sln"), settings);
+    var msBuildSettings =
+        new MSBuildSettings().WithLogger(
+            "BinaryLogger," + Context.Tools.Resolve("Cake.Issues.MsBuild*/**/StructuredLogger.dll"),
+            "",
+            msBuildLogFile)
+    DotNetBuild(
+        repoRootPath.CombineWithFilePath("MySolution.sln"),
+        new DotNetBuildSettings{MSBuildSettings = msBuildSettings});
 
     // Write issues to console.
     CreateIssueReport(
         new List<IIssueProvider>
         {
             MsBuildIssuesFromFilePath(
                 msBuildLogFile,
-                MsBuildXmlFileLoggerFormat)
+                MsBuildBinaryLogFileFormat)
         },
         ConsoleIssueReportFormat(
             new ConsoleIssueReportFormatSettings
@@ -49,5 +46,3 @@ Task("Create-IssueReport").Does(() =>
         string.Empty);
 });
 ```
-
---8<-- "snippets/pinning.md"
diff --git a/docs/docs/documentation/report-formats/generic/examples/custom-template.md b/docs/docs/documentation/report-formats/generic/examples/custom-template.md
@@ -10,7 +10,6 @@ description: Example how to create a report using a custom template
 The following example will create a HTML report for issues logged as warnings by MsBuild using a custom template.
 
 ```csharp
-#tool "nuget:?package=MSBuild.Extension.Pack" // (1)!
 #addin nuget:?package=Cake.Issues&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.MsBuild&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.Reporting&version={{ cake_issues_version }}
@@ -20,35 +19,31 @@ Task("Create-IssueReport").Does(() =>
 {
     var repoRootFolder = new DirectoryPath(@"c:\repo");
 
-    // Build MySolution.sln solution in the repository root folder and log issues
-    // using XmlFileLogger from MSBuild Extension Pack.
+    // Build MySolution.sln solution in the repository root folder and write a binary log.
     FilePath msBuildLogFile = @"c:\build\msbuild.log";
-    var settings = new MsBuildSettings()
-        .WithLogger(
-            Context.Tools.Resolve("MSBuild.ExtensionPack.Loggers.dll").FullPath,
-            "XmlFileLogger",
-            string.Format(
-                "logfile=\"{0}\";verbosity=Detailed;encoding=UTF-8",
-                msBuildLogFile)
-        );
-    MSBuild(repoRootFolder.CombineWithFilePath("MySolution.sln"), settings);
+    var msBuildSettings =
+        new MSBuildSettings().WithLogger(
+            "BinaryLogger," + Context.Tools.Resolve("Cake.Issues.MsBuild*/**/StructuredLogger.dll"),
+            "",
+            msBuildLogFile)
+    DotNetBuild(
+        repoRootPath.CombineWithFilePath("MySolution.sln"),
+        new DotNetBuildSettings{MSBuildSettings = msBuildSettings});
 
     // Create HTML report using Diagnostic template.
     CreateIssueReport(
         new List<IIssueProvider>
         {
             MsBuildIssuesFromFilePath(
                 msBuildLogFile,
-                MsBuildXmlFileLoggerFormat)
+                MsBuildBinaryLogFileFormat)
         },
         GenericIssueReportFormatFromFilePath(@"c:\ReportTemplate.cshtml"),
         repoRootFolder,
         @"c:\report.html");
 });
 ```
 
---8<-- "snippets/pinning.md"
-
 `ReportTemplate` looks like this:
 
 ```csharp

diff --git a/docs/docs/documentation/report-formats/generic/examples/default-template.md b/docs/docs/documentation/report-formats/generic/examples/default-template.md
@@ -6,7 +6,6 @@ description: Example how to create a report using an embedded default template.
 The following example will create a HTML report for issues logged as warnings by MsBuild.
 
 ```csharp
-#tool "nuget:?package=MSBuild.Extension.Pack" // (1)!
 #addin nuget:?package=Cake.Issues&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.MsBuild&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.Reporting&version={{ cake_issues_version }}
@@ -16,31 +15,27 @@ Task("Create-IssueReport").Does(() =>
 {
     var repoRootFolder = new DirectoryPath(@"c:\repo");
 
-    // Build MySolution.sln solution in the repository root folder and log issues
-    // using XmlFileLogger from MSBuild Extension Pack.
+    // Build MySolution.sln solution in the repository root folder and write a binary log.
     FilePath msBuildLogFile = @"c:\build\msbuild.log";
-    var settings = new MsBuildSettings()
-        .WithLogger(
-            Context.Tools.Resolve("MSBuild.ExtensionPack.Loggers.dll").FullPath,
-            "XmlFileLogger",
-            string.Format(
-                "logfile=\"{0}\";verbosity=Detailed;encoding=UTF-8",
-                msBuildLogFile)
-        );
-    MSBuild(repoRootFolder.CombineWithFilePath("MySolution.sln"), settings);
+    var msBuildSettings =
+        new MSBuildSettings().WithLogger(
+            "BinaryLogger," + Context.Tools.Resolve("Cake.Issues.MsBuild*/**/StructuredLogger.dll"),
+            "",
+            msBuildLogFile)
+    DotNetBuild(
+        repoRootPath.CombineWithFilePath("MySolution.sln"),
+        new DotNetBuildSettings{MSBuildSettings = msBuildSettings});
 
     // Create HTML report using Diagnostic template.
     CreateIssueReport(
         new List<IIssueProvider>
         {
             MsBuildIssuesFromFilePath(
                 msBuildLogFile,
-                MsBuildXmlFileLoggerFormat)
+                MsBuildBinaryLogFileFormat)
         },
         GenericIssueReportFormatFromEmbeddedTemplate(GenericIssueReportTemplate.HtmlDiagnostic),
         repoRootFolder,
         @"c:\report.html");
 });
 ```
-
---8<-- "snippets/pinning.md"
diff --git a/docs/docs/documentation/report-formats/sarif/examples.md b/docs/docs/documentation/report-formats/sarif/examples.md
@@ -7,7 +7,6 @@ icon: material/test-tube
 The following example will create a SARIF report for issues logged as warnings by MsBuild.
 
 ```csharp
-#tool "nuget:?package=MSBuild.Extension.Pack" // (1)!
 #addin nuget:?package=Cake.Issues&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.MsBuild&version={{ cake_issues_version }}
 #addin nuget:?package=Cake.Issues.Reporting&version={{ cake_issues_version }}
@@ -17,31 +16,27 @@ Task("Create-IssueReport").Does(() =>
 {
     var repoRootFolder = new DirectoryPath(@"c:\repo");
 
-    // Build MySolution.sln solution in the repository root folder and log issues
-    // using XmlFileLogger from MSBuild Extension Pack.
+    // Build MySolution.sln solution in the repository root folder and write a binary log.
     FilePath msBuildLogFile = @"c:\build\msbuild.log";
-    var settings = new MsBuildSettings()
-        .WithLogger(
-            Context.Tools.Resolve("MSBuild.ExtensionPack.Loggers.dll").FullPath,
-            "XmlFileLogger",
-            string.Format(
-                "logfile=\"{0}\";verbosity=Detailed;encoding=UTF-8",
-                msBuildLogFile)
-        );
-    MSBuild(repoRootFolder.CombineWithFilePath("MySolution.sln"), settings);
+    var msBuildSettings =
+        new MSBuildSettings().WithLogger(
+            "BinaryLogger," + Context.Tools.Resolve("Cake.Issues.MsBuild*/**/StructuredLogger.dll"),
+            "",
+            msBuildLogFile)
+    DotNetBuild(
+        repoRootPath.CombineWithFilePath("MySolution.sln"),
+        new DotNetBuildSettings{MSBuildSettings = msBuildSettings});
 
     // Create SARIF report.
     CreateIssueReport(
         new List<IIssueProvider>
         {
             MsBuildIssuesFromFilePath(
                 msBuildLogFile,
-                MsBuildXmlFileLoggerFormat)
+                MsBuildBinaryLogFileFormat)
         },
         SarifIssueReportFormat(),
         repoRootFolder,
         @"c:\report.sarif");
 });
 ```
-
---8<-- "snippets/pinning.md"
diff --git a/docs/docs/documentation/usage/creating-reports/creating-reports.md b/docs/docs/documentation/usage/creating-reports/creating-reports.md
@@ -28,7 +28,7 @@ Task("Create-Report").Does(() =>
     CreateIssueReport(
         MsBuildIssuesFromFilePath(
             @"C:\build\msbuild.log",
-            MsBuildXmlFileLoggerFormat),
+            MsBuildBinaryLogFileFormat),
         GenericIssueReportFormatFromEmbeddedTemplate(GenericIssueReportTemplate.HtmlDiagnostic),
         repoRootFolder,
         @"c:\report.html");

diff --git a/docs/docs/documentation/usage/reading-issues/file-linking.md b/docs/docs/documentation/usage/reading-issues/file-linking.md
@@ -12,7 +12,7 @@ var settings =
     {
         FileLinkSettings =
             IssueFileLinkSettingsForGitHubCommit(
-                "https://github.com/cake-contrib/Cake.Issues.Reporting.Generic",
+                "https://github.com/cake-contrib/Cake.Issues",
                 "76a7cacef7ad4295a6766646d45c9b56")
     };
 

diff --git a/docs/docs/documentation/usage/reading-issues/reading-issues.md b/docs/docs/documentation/usage/reading-issues/reading-issues.md
@@ -22,8 +22,8 @@ and from JetBrains InspectCode are imported:
 ```
 
 Finally you can define a task where you call the core addin with the desired issue providers.
-The following example reads issues reported as MsBuild warnings by the `XmlFileLogger`
-class from [MSBuild Extension Pack](http://www.msbuildextensionpack.com/){target="_blank"} and issues reported by JetBrains InspectCode:
+The following example reads warnings and errors reported by MsBuild from a binary log
+and issues reported by JetBrains InspectCode:
 
 ```csharp
 Task("Read-Issues").Does(() =>
@@ -34,7 +34,7 @@ Task("Read-Issues").Does(() =>
         {
             MsBuildIssuesFromFilePath(
                 @"C:\build\msbuild.log",
-                MsBuildXmlFileLoggerFormat),
+                MsBuildBinaryLogFileFormat),
             InspectCodeIssuesFromFilePath(
                 @"C:\build\inspectcode.log")
         },