Merge branch 'dev'

BenchManager/BenchDashboard/Properties/AssemblyInfo.cs

@@ -32,5 +32,5 @@
 // You can specify all the values or you can default the Build and Revision Numbers 
 // by using the '*' as shown below:
 // [assembly: AssemblyVersion("1.0.*")]
-[assembly: AssemblyVersion("0.11.4.0")]
-[assembly: AssemblyFileVersion("0.11.4.0")]
+[assembly: AssemblyVersion("0.12.0.0")]
+[assembly: AssemblyFileVersion("0.12.0.0")]

BenchManager/BenchLib/ActivationFile.cs

@@ -7,6 +7,33 @@
 
 namespace Mastersign.Bench
 {
+    /// <summary>
+    /// <para>Represents a text file with a list of app IDs.</para>
+    /// <para>
+    /// The syntax of the text file follows the following rules:
+    /// </para>
+    /// <list type="bullet">
+    ///     <item>Empty lines are ignored.</item>
+    ///     <item>Lines with nothing but white space are ignored.</item>
+    ///     <item>White space at the beginning and the end of lines is trimmed.</item>
+    ///     <item>Lines starting with <c>#</c> are ignored.</item>
+    ///     <item>The first word (contiguous non white space) in a line is considered to be an app ID.</item>
+    ///     <item>Additional characters after the first word are ignored, and can be used to commment the entry.</item>
+    /// </list>
+    /// <example>
+    /// A text file represented by this class could look like this:
+    /// <code>
+    /// # --- Activated Apps --- #
+    /// 
+    /// AppA
+    /// AppB (this app has a comment)
+    ///  AppC (this app ID is valid, despite the fact, that it is indended)
+    ///  
+    /// # AppD (this app is not activated, because the line is commented out)
+    /// AppE some arbitrary comment
+    /// </code>
+    /// </example>
+    /// </summary>
     public class ActivationFile : IEnumerable<string>
     {
         private static readonly Regex SpaceExp = new Regex(@"\s");
@@ -15,6 +42,10 @@ public class ActivationFile : IEnumerable<string>
 
         private readonly string FilePath;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="ActivationFile"/>.
+        /// </summary>
+        /// <param name="path">An absolute path to the text file.</param>
         public ActivationFile(string path)
         {
             FilePath = path;
@@ -91,16 +122,38 @@ private static IEnumerable<string> Deactivator(IEnumerable<string> lines, string
             }
         }
 
+        /// <summary>
+        /// Makes shure, the given app ID is listed active.<br/>
+        /// The text file is updated immediately.
+        /// </summary>
+        /// <remarks>
+        /// If the given app ID is already listed, but commented out, the commenting <c>#</c> is removed.
+        /// If the given app ID is not listed, it is added at the end of the file.
+        /// </remarks>
+        /// <param name="id">An app ID. Must be a string without whitespace.</param>
         public void SignIn(string id)
         {
             EditFile(lines => Activator(lines, id));
         }
 
+        /// <summary>
+        /// Makes shure, the given app ID is not listed active.<br/>
+        /// The text file is updated immediately.
+        /// </summary>
+        /// <remarks>
+        /// If the given app ID is not listed, or commented out, the text file is not changed.
+        /// If the given app ID is listed and not commented out, its line is prepended with a <c># </c> to comment it out.
+        /// </remarks>
+        /// <param name="id">An app ID. Must be a string without whitespace.</param>
         public void SignOut(string id)
         {
             EditFile(lines => Deactivator(lines, id));
         }
 
+        /// <summary>
+        /// Returns all app IDs listed as active.
+        /// </summary>
+        /// <returns>An enumerator of strings.</returns>
         public IEnumerator<string> GetEnumerator()
         {
             if (!File.Exists(FilePath)) yield break;

BenchManager/BenchLib/AppArchiveTyps.cs

@@ -4,7 +4,7 @@
 
 namespace Mastersign.Bench
 {
-    public static class AppArchiveTyps
+    internal static class AppArchiveTyps
     {
         public const string Auto = "auto";
         public const string Generic = "generic";

BenchManager/BenchLib/AppFacade.cs

@@ -283,10 +283,15 @@ public string GetLauncherScriptFile()
 
         public string GetCustomScriptFile(string typ)
         {
-            var path = IOPath.Combine(
+            var userPath = IOPath.Combine(
+                IOPath.Combine(AppIndex.GetStringValue(PropertyKeys.CustomConfigDir), "apps"),
+                ID.ToLowerInvariant() + "." + typ + ".ps1");
+            if (File.Exists(userPath)) return userPath;
+            var integratedPath = IOPath.Combine(
                 IOPath.Combine(AppIndex.GetStringValue(PropertyKeys.BenchAuto), "apps"),
                 ID.ToLowerInvariant() + "." + typ + ".ps1");
-            return File.Exists(path) ? path : null;
+            if (File.Exists(integratedPath)) return integratedPath;
+            return null;
         }
 
         #endregion

BenchManager/BenchLib/AppIndexDefaultValueSource.cs

@@ -5,7 +5,7 @@
 
 namespace Mastersign.Bench
 {
-    public class AppIndexDefaultValueSource : IGroupedPropertySource
+    internal class AppIndexDefaultValueSource : IGroupedPropertySource
     {
         public IGroupedPropertySource AppIndex { get; set; }
 

BenchManager/BenchLib/AppIndexFacade.cs

@@ -5,6 +5,12 @@
 
 namespace Mastersign.Bench
 {
+    /// <summary>
+    /// <para>A collection of Bench apps.</para>
+    /// <para>
+    /// This class provides a facade to handle the properties and the states of the bench apps
+    /// in an object-oriented fashion.</para>
+    /// </summary>
     public class AppIndexFacade : IEnumerable<AppFacade>
     {
         private readonly IConfiguration AppIndex;
@@ -22,28 +28,56 @@ private AppFacade GetAppFacade(string appName)
             return app;
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="AppIndexFacade"/>.
+        /// </summary>
+        /// <param name="appIndex">An instance of <see cref="IConfiguration"/> holding the configuration of Bench apps.</param>
         public AppIndexFacade(IConfiguration appIndex)
         {
             AppIndex = appIndex;
         }
 
+        /// <summary>
+        /// Gets an instance of <see cref="AppFacade"/> for the specified app.
+        /// </summary>
+        /// <param name="appName">The ID of an app.</param>
+        /// <returns>The facade for the app, or <c>null</c>.</returns>
         public AppFacade this[string appName]
         {
             get { return Exists(appName) ? GetAppFacade(appName) : null; }
         }
 
+        /// <summary>
+        /// Gets a collection with <see cref="AppFacade"/> objects for multiple apps.
+        /// </summary>
+        /// <remarks>
+        /// If an app ID can not be found, a <c>null</c> is placed in the returned collection.
+        /// Therefore, the returned collection has always the same number of items as the given enumeration.
+        /// </remarks>
+        /// <param name="appNames">An enumeration with app IDs.</param>
+        /// <returns>A collection with facades.</returns>
         public ICollection<AppFacade> GetApps(IEnumerable<string> appNames)
         {
             var result = new List<AppFacade>();
             foreach (var appName in appNames) result.Add(GetAppFacade(appName));
             return result;
         }
 
+        /// <summary>
+        /// Checks whether an app ID exists in the app index.
+        /// </summary>
+        /// <param name="appName">The app ID.</param>
+        /// <returns><c>true</c> if the app was found; otherwise <c>false</c>.</returns>
         public bool Exists(string appName)
         {
             return AppIndex.ContainsGroup(appName);
         }
 
+        /// <summary>
+        /// Gets all apps of a given category.
+        /// </summary>
+        /// <param name="category">The app category.</param>
+        /// <returns>An array with facades for all apps in the given category.</returns>
         public AppFacade[] ByCategory(string category)
         {
             var appNames = AppIndex.GroupsByCategory(category);
@@ -55,6 +89,9 @@ public AppFacade[] ByCategory(string category)
             return result.ToArray();
         }
 
+        /// <summary>
+        /// Gets an array with facades for all active apps.
+        /// </summary>
         public AppFacade[] ActiveApps
         {
             get
@@ -72,6 +109,9 @@ public AppFacade[] ActiveApps
             }
         }
 
+        /// <summary>
+        /// Gets an array with facades for all inactive apps.
+        /// </summary>
         public AppFacade[] InactiveApps
         {
             get
@@ -89,6 +129,9 @@ public AppFacade[] InactiveApps
             }
         }
 
+        /// <summary>
+        /// Gets an array with facades for all apps required by Bench itself.
+        /// </summary>
         public AppFacade[] RequiredApps
         {
             get
@@ -106,6 +149,10 @@ public AppFacade[] RequiredApps
             }
         }
 
+        /// <summary>
+        /// Gets the facades for all apps in the index.
+        /// </summary>
+        /// <returns>An enumerator with <see cref="AppFacade"/> objects.</returns>
         public IEnumerator<AppFacade> GetEnumerator()
         {
             foreach (var appName in AppIndex.Groups())
@@ -119,6 +166,9 @@ IEnumerator IEnumerable.GetEnumerator()
             return GetEnumerator();
         }
 
+        /// <summary>
+        /// Gets an array with the paths for environment registration of all activated apps.
+        /// </summary>
         public string[] EnvironmentPath
         {
             get
@@ -139,6 +189,11 @@ public string[] EnvironmentPath
             }
         }
 
+        /// <summary>
+        /// Gets a dictionary with the merged environment variables of all activated apps.
+        /// That excludes the <c>PATH</c> environment variable, which is handeled
+        /// separatly in <see cref="EnvironmentPath"/>.
+        /// </summary>
         public IDictionary<string, string> Environment
         {
             get

BenchManager/BenchLib/AppIndexValueResolver.cs

@@ -4,7 +4,7 @@
 
 namespace Mastersign.Bench
 {
-    public class AppIndexValueResolver : IGroupedValueResolver
+    internal class AppIndexValueResolver : IGroupedValueResolver
     {
         private static readonly char[] KeyValueSeparator = new char[] { ':' };
 

BenchManager/BenchLib/AppKeys.cs

@@ -4,19 +4,39 @@
 
 namespace Mastersign.Bench
 {
+    /// <summary>
+    /// This static class contains constants for the IDs of apps directly known by the Bench system.
+    /// </summary>
     public static class AppKeys
     {
-        public const string SevenZip = "SvZ";
+        /// <summary>The app ID of 7-Zip.</summary>
+        public const string SevenZip = "7z";
+
+        /// <summary>The app ID of Less MSI.</summary>
         public const string LessMSI = "LessMsi";
+
+        /// <summary>The app ID of Inno Setup Unpacker.</summary>
         public const string InnoSetupUnpacker = "InnoUnp";
 
+        /// <summary>The app ID of ConEmu.</summary>
         public const string ConEmu = "ConEmu";
+
+        /// <summary>The app ID of Git.</summary>
         public const string Git = "Git";
 
+        /// <summary>The app ID of Node.js.</summary>
         public const string NodeJS = "Node";
+
+        /// <summary>The app ID of the Node.js package manager.</summary>
         public const string Npm = "Npm";
+
+        /// <summary>The app ID of Ruby.</summary>
         public const string Ruby = "Ruby";
+
+        /// <summary>The app ID of Python 2.</summary>
         public const string Python2 = "Python2";
+
+        /// <summary>The app ID of Python 3.</summary>
         public const string Python3 = "Python3";
     }
 }

BenchManager/BenchLib/AppStatusIcon.cs

@@ -1,14 +1,48 @@
 namespace Mastersign.Bench
 {
+    /// <summary>
+    /// The enumeration of possible status icon types of an app.
+    /// </summary>
     public enum AppStatusIcon
     {
+        /// <summary>
+        /// No status icon. The app is not activated, not installed, and not cached.
+        /// </summary>
         None,
+
+        /// <summary>
+        /// The app is activated and the status of the app is OK.
+        /// </summary>
         OK,
+
+        /// <summary>
+        /// There is an info message, regarding this app.
+        /// </summary>
         Info,
+
+        /// <summary>
+        /// The app is not activated, but is is cached.
+        /// </summary>
         Cached,
+
+        /// <summary>
+        /// The app is not activated, but installed.
+        /// </summary>
         Tolerated,
+
+        /// <summary>
+        /// The app is explicitly deactivated.
+        /// </summary>
         Blocked,
+
+        /// <summary>
+        /// There is a pending task, regarding this app.
+        /// </summary>
         Task,
+
+        /// <summary>
+        /// There is an error message, regarding this app.
+        /// </summary>
         Warning
     }
 }

BenchManager/BenchLib/AppTyps.cs

@@ -4,13 +4,27 @@
 
 namespace Mastersign.Bench
 {
+    /// <summary>
+    /// This static class contains string constants for the app types known to Bench.
+    /// </summary>
     public static class AppTyps
     {
+        /// <summary>The name of the default app typ.</summary>
         public const string Default = "default";
+
+        /// <summary>The name of the meta app typ for custom apps and groups.</summary>
         public const string Meta = "meta";
+
+        /// <summary>The name of the app typ for Node.js packages, managed by npm.</summary>
         public const string NodePackage = "node-package";
+
+        /// <summary>The name of the app typ for Ruby gems.</summary>
         public const string RubyPackage = "ruby-package";
+
+        /// <summary>The name of the app typ for Python 2 packages, managed by PIP.</summary>
         public const string Python2Package = "python2-package";
+
+        /// <summary>The name of the app typ for Python 3 packages, managed by PIP.</summary>
         public const string Python3Package = "python3-package";
     }
 }