Merge pull request #237 from christianbumann/feature/gh-234

(GH-234) Add an alias to get builds by specific settings

Author: pascalberger

src/Cake.AzureDevOps.Tests/Pipelines/AzureDevOpsSettingsTests.cs

@@ -89,6 +89,43 @@ public static AzureDevOpsBuild AzureDevOpsBuildUsingAzurePipelinesOAuthToken(
             return AzureDevOpsBuild(context, settings);
         }
 
+        /// <summary>
+        /// Gets Azure Pipelines builds using the specified settings.
+        /// </summary>
+        /// <param name="context">The context.</param>
+        /// <param name="settings">Settings for getting the build.</param>
+        /// <example>
+        /// <para>Get builds running on Azure DevOps Server:</para>
+        /// <code>
+        /// <![CDATA[
+        /// var buildSettings =
+        ///     new AzureDevOpsBuildsSettings(
+        ///         new Uri("http://myserver:8080/defaultcollection"),
+        ///         "MyProject",
+        ///         AzureDevOpsAuthenticationNtlm());
+        ///
+        /// var builds =
+        ///     AzureDevOpsBuilds(
+        ///         buildSettings);
+        /// ]]>
+        /// </code>
+        /// </example>
+        /// <returns>Description of the builds or an empty list of builds.</returns>
+        [CakeMethodAlias]
+        [CakeAliasCategory("Azure Pipelines")]
+        [CakeNamespaceImport("Cake.AzureDevOps.Pipelines")]
+        public static IEnumerable<AzureDevOpsBuild> AzureDevOpsBuilds(
+            this ICakeContext context,
+            AzureDevOpsBuildsSettings settings)
+        {
+            context.NotNull(nameof(context));
+            settings.NotNull(nameof(settings));
+
+            return AzureDevOpsBuildsHelper.GetAzureDevOpsBuilds(
+                context.Log,
+                settings);
+        }
+
         /// <summary>
         /// Returns if the Azure DevOps build is failing.
         /// </summary>

src/Cake.AzureDevOps/AzureDevOpsAliases.Pipelines.cs

@@ -0,0 +1,61 @@
+namespace Cake.AzureDevOps
+{
+    using System;
+
+    /// <summary>
+    /// Class for reading environment variables.
+    /// </summary>
+    internal static class EnvironmentVariableHelper
+    {
+        /// <summary>
+        /// Gets the value for the environment variable 'SYSTEM_ACCESSTOKEN'.
+        /// </summary>
+        /// <returns>The value for the environment variable 'SYSTEM_ACCESSTOKEN'.</returns>
+        /// <exception cref="InvalidOperationException">If the environment variable was not found or the value is whitespace.</exception>
+        public static string GetSystemAccessToken()
+        {
+            var accessToken = Environment.GetEnvironmentVariable("SYSTEM_ACCESSTOKEN", EnvironmentVariableTarget.Process);
+            if (string.IsNullOrWhiteSpace(accessToken))
+            {
+                throw new InvalidOperationException(
+                    "Failed to read the SYSTEM_ACCESSTOKEN environment variable. Make sure you are running in an Azure Pipelines build and that the 'Allow Scripts to access OAuth token' option is enabled.");
+            }
+
+            return accessToken;
+        }
+
+        /// <summary>
+        /// Gets the value for the environment variable 'SYSTEM_TEAMFOUNDATIONCOLLECTIONURI'.
+        /// </summary>
+        /// <returns>The value for the environment variable 'SYSTEM_TEAMFOUNDATIONCOLLECTIONURI'.</returns>
+        /// <exception cref="InvalidOperationException">If the environment variable was not found or the value is whitespace.</exception>
+        public static Uri GetSystemTeamFoundationCollectionUri()
+        {
+            var collectionUrl = Environment.GetEnvironmentVariable("SYSTEM_TEAMFOUNDATIONCOLLECTIONURI", EnvironmentVariableTarget.Process);
+            if (string.IsNullOrWhiteSpace(collectionUrl))
+            {
+                throw new InvalidOperationException(
+                    "Failed to read the SYSTEM_TEAMFOUNDATIONCOLLECTIONURI environment variable. Make sure you are running in an Azure Pipelines build.");
+            }
+
+            return new Uri(collectionUrl);
+        }
+
+        /// <summary>
+        /// Gets the value for the environment variable 'SYSTEM_TEAMPROJECT'.
+        /// </summary>
+        /// <returns>The value for the environment variable 'SYSTEM_TEAMPROJECT'.</returns>
+        /// <exception cref="InvalidOperationException">If the environment variable was not found or the value is whitespace.</exception>
+        public static string GetSystemTeamProject()
+        {
+            var projectName = Environment.GetEnvironmentVariable("SYSTEM_TEAMPROJECT", EnvironmentVariableTarget.Process);
+            if (string.IsNullOrWhiteSpace(projectName))
+            {
+                throw new InvalidOperationException(
+                    "Failed to read the SYSTEM_TEAMPROJECT environment variable. Make sure you are running in an Azure Pipelines build.");
+            }
+
+            return projectName;
+        }
+    }
+}

src/Cake.AzureDevOps/EnvironmentVariableHelper.cs

@@ -30,6 +30,25 @@ public AzureDevOpsBuild(ICakeLog log, AzureDevOpsBuildSettings settings)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AzureDevOpsBuild"/> class.
+        /// </summary>
+        /// <param name="log">The Cake log context.</param>
+        /// <param name="settings">Settings for accessing AzureDevOps.</param>
+        /// <param name="build">The build.</param>
+        internal AzureDevOpsBuild(ICakeLog log, AzureDevOpsBuildsSettings settings, Build build)
+        {
+            log.NotNull(nameof(log));
+            settings.NotNull(nameof(settings));
+            build.NotNull(nameof(build));
+
+            this.log = log;
+            this.build = build;
+            this.buildClientFactory = new BuildClientFactory();
+            this.credentials = settings.Credentials;
+            this.CollectionUrl = settings.CollectionUrl;
+        }
+
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureDevOpsBuild"/> class.
         /// </summary>

src/Cake.AzureDevOps/Pipelines/AzureDevOpsBuild.cs

@@ -0,0 +1,38 @@
+namespace Cake.AzureDevOps.Pipelines
+{
+    /// <summary>
+    /// Possible order of a build query.
+    /// </summary>
+    public enum AzureDevOpsBuildQueryOrder : byte
+    {
+        /// <summary>
+        /// Order by finish time ascending.
+        /// </summary>
+        FinishTimeAscending = 2,
+
+        /// <summary>
+        /// Order by finish time descending.
+        /// </summary>
+        FinishTimeDescending = 3,
+
+        /// <summary>
+        /// Order by queue time descending.
+        /// </summary>
+        QueueTimeDescending = 4,
+
+        /// <summary>
+        /// Order by queue time ascending.
+        /// </summary>
+        QueueTimeAscending = 5,
+
+        /// <summary>
+        /// Order by start time descending.
+        /// </summary>
+        StartTimeDescending = 6,
+
+        /// <summary>
+        /// Order by start time ascending.
+        /// </summary>
+        StartTimeAscending = 7,
+    }
+}

src/Cake.AzureDevOps/Pipelines/AzureDevOpsBuildQueryOrder.cs

@@ -0,0 +1,36 @@
+namespace Cake.AzureDevOps.Pipelines
+{
+    using Microsoft.TeamFoundation.Build.WebApi;
+
+    /// <summary>
+    /// Extensions for the <see cref="AzureDevOpsBuildQueryOrder"/> class.
+    /// </summary>
+    internal static class AzureDevOpsBuildQueryOrderExtensions
+    {
+        /// <summary>
+        /// Converts a <see cref="AzureDevOpsBuildQueryOrderExtensions"/> to an <see cref="BuildQueryOrder"/>.
+        /// </summary>
+        /// <param name="queryOrder">Query order to convert.</param>
+        /// <returns>Converted query order.</returns>
+        public static BuildQueryOrder ToBuildQueryOrder(this AzureDevOpsBuildQueryOrder queryOrder)
+        {
+            switch (queryOrder)
+            {
+                case AzureDevOpsBuildQueryOrder.FinishTimeAscending:
+                    return BuildQueryOrder.FinishTimeAscending;
+                case AzureDevOpsBuildQueryOrder.FinishTimeDescending:
+                    return BuildQueryOrder.FinishTimeDescending;
+                case AzureDevOpsBuildQueryOrder.QueueTimeDescending:
+                    return BuildQueryOrder.QueueTimeDescending;
+                case AzureDevOpsBuildQueryOrder.QueueTimeAscending:
+                    return BuildQueryOrder.QueueTimeAscending;
+                case AzureDevOpsBuildQueryOrder.StartTimeDescending:
+                    return BuildQueryOrder.StartTimeDescending;
+                case AzureDevOpsBuildQueryOrder.StartTimeAscending:
+                    return BuildQueryOrder.StartTimeAscending;
+                default:
+                    throw new System.Exception("Unknown value");
+            }
+        }
+    }
+}

src/Cake.AzureDevOps/Pipelines/AzureDevOpsBuildQueryOrderExtensions.cs

@@ -0,0 +1,34 @@
+namespace Cake.AzureDevOps.Pipelines
+{
+    using Microsoft.TeamFoundation.Build.WebApi;
+
+    /// <summary>
+    /// Extensions for the <see cref="AzureDevOpsBuildResult"/> class.
+    /// </summary>
+    internal static class AzureDevOpsBuildResultExtensions
+    {
+        /// <summary>
+        /// Converts a <see cref="AzureDevOpsBuildResult"/> to an <see cref="BuildResult"/>.
+        /// </summary>
+        /// <param name="result">Build result to convert.</param>
+        /// <returns>Converted build result.</returns>
+        public static BuildResult ToBuildResult(this AzureDevOpsBuildResult result)
+        {
+            switch (result)
+            {
+                case AzureDevOpsBuildResult.None:
+                    return BuildResult.None;
+                case AzureDevOpsBuildResult.Succeeded:
+                    return BuildResult.Succeeded;
+                case AzureDevOpsBuildResult.PartiallySucceeded:
+                    return BuildResult.PartiallySucceeded;
+                case AzureDevOpsBuildResult.Failed:
+                    return BuildResult.Failed;
+                case AzureDevOpsBuildResult.Canceled:
+                    return BuildResult.Canceled;
+                default:
+                    throw new System.Exception("Unknown value");
+            }
+        }
+    }
+}

src/Cake.AzureDevOps/Pipelines/AzureDevOpsBuildResultExtensions.cs

@@ -73,32 +73,16 @@ public AzureDevOpsBuildSettings(AzureDevOpsBuildSettings settings)
 
         /// <summary>
         /// Initializes a new instance of the <see cref="AzureDevOpsBuildSettings"/> class using environment variables
-        /// as set by a Azure Pipelines build.
+        /// as set by an Azure Pipelines build.
         /// </summary>
         /// <param name="credentials">Credentials to use to authenticate against Azure DevOps.</param>
         public AzureDevOpsBuildSettings(IAzureDevOpsCredentials credentials)
         {
             credentials.NotNull(nameof(credentials));
 
             this.Credentials = credentials;
-
-            var collectionUrl = Environment.GetEnvironmentVariable("SYSTEM_TEAMFOUNDATIONCOLLECTIONURI", EnvironmentVariableTarget.Process);
-            if (string.IsNullOrWhiteSpace(collectionUrl))
-            {
-                throw new InvalidOperationException(
-                    "Failed to read the SYSTEM_TEAMFOUNDATIONCOLLECTIONURI environment variable. Make sure you are running in an Azure Pipelines build.");
-            }
-
-            this.CollectionUrl = new Uri(collectionUrl);
-
-            var projectName = Environment.GetEnvironmentVariable("SYSTEM_TEAMPROJECT", EnvironmentVariableTarget.Process);
-            if (string.IsNullOrWhiteSpace(projectName))
-            {
-                throw new InvalidOperationException(
-                    "Failed to read the SYSTEM_TEAMPROJECT environment variable. Make sure you are running in an Azure Pipelines build.");
-            }
-
-            this.ProjectName = projectName;
+            this.CollectionUrl = EnvironmentVariableHelper.GetSystemTeamFoundationCollectionUri();
+            this.ProjectName = EnvironmentVariableHelper.GetSystemTeamProject();
 
             var buildId = Environment.GetEnvironmentVariable("BUILD_BUILDID", EnvironmentVariableTarget.Process);
             if (string.IsNullOrWhiteSpace(buildId))
@@ -159,14 +143,7 @@ public AzureDevOpsBuildSettings(IAzureDevOpsCredentials credentials)
         /// <returns>The instance of <see cref="AzureDevOpsBuildSettings"/> class.</returns>
         public static AzureDevOpsBuildSettings UsingAzurePipelinesOAuthToken()
         {
-            var accessToken = Environment.GetEnvironmentVariable("SYSTEM_ACCESSTOKEN", EnvironmentVariableTarget.Process);
-
-            if (string.IsNullOrWhiteSpace(accessToken))
-            {
-                throw new InvalidOperationException(
-                    "Failed to read the SYSTEM_ACCESSTOKEN environment variable. Make sure you are running in an Azure Pipelines build and that the 'Allow Scripts to access OAuth token' option is enabled.");
-            }
-
+            var accessToken = EnvironmentVariableHelper.GetSystemAccessToken();
             return new AzureDevOpsBuildSettings(new AzureDevOpsOAuthCredentials(accessToken));
         }
     }

src/Cake.AzureDevOps/Pipelines/AzureDevOpsBuildSettings.cs

@@ -0,0 +1,38 @@
+namespace Cake.AzureDevOps.Pipelines
+{
+    using Microsoft.TeamFoundation.Build.WebApi;
+
+    /// <summary>
+    /// Extensions for the <see cref="AzureDevOpsBuildStatus"/> class.
+    /// </summary>
+    internal static class AzureDevOpsBuildStatusExtensions
+    {
+        /// <summary>
+        /// Converts a <see cref="AzureDevOpsBuildStatus"/> to an <see cref="BuildStatus"/>.
+        /// </summary>
+        /// <param name="status">State to convert.</param>
+        /// <returns>Converted state.</returns>
+        public static BuildStatus ToBuildStatus(this AzureDevOpsBuildStatus status)
+        {
+            switch (status)
+            {
+                case AzureDevOpsBuildStatus.None:
+                    return BuildStatus.None;
+                case AzureDevOpsBuildStatus.InProgress:
+                    return BuildStatus.InProgress;
+                case AzureDevOpsBuildStatus.Completed:
+                    return BuildStatus.Completed;
+                case AzureDevOpsBuildStatus.Cancelling:
+                    return BuildStatus.Cancelling;
+                case AzureDevOpsBuildStatus.Postponed:
+                    return BuildStatus.Postponed;
+                case AzureDevOpsBuildStatus.NotStarted:
+                    return BuildStatus.NotStarted;
+                case AzureDevOpsBuildStatus.All:
+                    return BuildStatus.All;
+                default:
+                    throw new System.Exception("Unknown value");
+            }
+        }
+    }
+}