IXProjectEnv improvements, fixes, and other relevant changes due to v…

…sSolutionBuildEvent:

3F/vsSolutionBuildEvent#53
#17

## IConfPlatform changes:

+`bool IsEqualByRule(string config, string platform, bool icase = false);`

    Checking an config/platform by using {Rule} instance.

## IXProjectEnv changes:

+`IXProject XProjectByFile(...);`

    Find project by full path to file.

+`IEnumerable<IXProject> Assign(IEnumerable<Project> projects = null);`

    Assign an existing `Microsoft.Build.Evaluation.Project` instances for local collection.

+`IXProject AddOrGet(Project project);`

    Adds `Microsoft.Build.Evaluation.Project` instance into IXProject collection if it does not exist.

+`ProjectItemCfg ExtractItemCfg(Project project);`

    Prepares data from `Microsoft.Build.Evaluation.Project` instance.

+`void UnloadAll(bool throwIfErr = true);`

    Unloads all evaluated projects at current time.

+`bool Unload(IXProject xp);`

    Unloads specified project.

+`IEnumerable<Project> ValidProjects`

    List of valid projects such as something except `.user` but contains FirstChild / LastChild XML node.

## ISlnResult changes:

+`string SolutionFile`

    Full path to an solution file.

## New extension methods:

```
+TVal GetOrDefault<TKey, TVal>(this IDictionary<TKey, TVal> data, TKey key, TVal def)
+bool IsEqual(this Project a, Project b)
+string GetSolutionDir(this Project eProject)
+string GetProjectRelativePath(this Project eProject)
+string GetConfig(this Project eProject)
+string GetPlatform(this Project eProject)
+string GetSolutionExt(this Project eProject)
```

## Other

* Removed pGuid checking from `IXProjectEnv.GetOrLoadProject()`
* Added `FileExt` type for work with `ProjectType` via its file only.

MvsSln/Core/ConfigItem.cs

@@ -45,7 +45,8 @@ public IRuleOfConfig Rule
         } = new RuleOfConfig();
 
         /// <summary>
-        /// To use virtual `Sensitivity` method in comparing objects.
+        /// To use an `Sensitivity` logic when comparing {IConfPlatform}
+        /// together with `==` , `!=`.
         /// </summary>
         public bool SensitivityComparing
         {
@@ -64,6 +65,10 @@ public string ConfigurationByRule
             get => Rule?.Configuration(Configuration);
         }
 
+        /// <summary>
+        /// {ConfigurationByRule} with optional case insensitive logic.
+        /// Uses {SensitivityComparing} flag.
+        /// </summary>
         public string ConfigurationByRuleICase
         {
             get => Sensitivity(ConfigurationByRule);
@@ -80,11 +85,31 @@ public string PlatformByRule
             get => Rule?.Platform(Platform);
         }
 
+        /// <summary>
+        /// {PlatformByRule} with optional case insensitive logic.
+        /// Uses {SensitivityComparing} flag.
+        /// </summary>
         public string PlatformByRuleICase
         {
             get => Sensitivity(PlatformByRule);
         }
 
+        /// <summary>
+        /// Checking an config/platform by using {Rule} instance.
+        /// </summary>
+        /// <param name="config">Configuration name.</param>
+        /// <param name="platform">Platform name.</param>
+        /// <param name="icase">Case insensitive flag.</param>
+        /// <returns></returns>
+        public bool IsEqualByRule(string config, string platform, bool icase = false)
+        {
+            var cmp = icase ? StringComparison.InvariantCultureIgnoreCase 
+                            : StringComparison.InvariantCulture;
+
+            return string.Equals(ConfigurationByRule, Rule?.Configuration(config), cmp)
+                && string.Equals(PlatformByRule, Rule?.Platform(platform), cmp);
+        }
+
         public static bool operator ==(ConfigItem a, ConfigItem b)
         {
             return Object.ReferenceEquals(a, null) ? 
@@ -104,6 +129,8 @@ public override bool Equals(object obj)
 
             var b = (ConfigItem)obj;
 
+            // NOTE: {SensitivityComparing} will control an `Sensitivity` logic, 
+            //       thus we need only `...ByRuleICase` properties:
             return ConfigurationByRuleICase == b.ConfigurationByRuleICase 
                     && PlatformByRuleICase == b.PlatformByRuleICase;
         }

MvsSln/Core/Guids.cs

@@ -25,29 +25,69 @@
 
 using System.Collections.Generic;
 using System.Linq;
+using net.r_eg.MvsSln.Extensions;
 
-// TODO: move to '.Types' namespace
+// TODO: move to '.Types' namespace and split ProjectType processing into new additional type.
 namespace net.r_eg.MvsSln.Core
 {
     public static class Guids
     {
         /// <summary>
         /// Solution Folder.
         /// </summary>
-        public const string SLN_FOLDER     = "{2150E333-8FDC-42A3-9474-1A3956D46DE8}";
+        public const string SLN_FOLDER = "{2150E333-8FDC-42A3-9474-1A3956D46DE8}";
 
-        public const string PROJECT_CS     = "{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}";
-        public const string PROJECT_DB     = "{C8D11400-126E-41CD-887F-60BD40844F9E}";
-        public const string PROJECT_FS     = "{F2A71F9B-5D33-465A-A702-920D77279786}";
-        public const string PROJECT_VB     = "{F184B08F-C81C-45F6-A57F-5ABD9991F28F}";
-        public const string PROJECT_VC     = "{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}";
-        public const string PROJECT_VJ     = "{E6FDF86B-F3D1-11D4-8576-0002A516ECE8}";
-        public const string PROJECT_WD     = "{2CFEAB61-6A3B-4EB8-B523-560B4BEEF521}";
-        public const string PROJECT_WEB    = "{E24C65DC-7377-472B-9ABA-BC803B73C61A}";
+        /// <summary>
+        /// .csproj
+        /// </summary>
+        public const string PROJECT_CS = "{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}";
+
+        /// <summary>
+        /// .dbproj
+        /// </summary>
+        public const string PROJECT_DB = "{C8D11400-126E-41CD-887F-60BD40844F9E}";
+
+        /// <summary>
+        /// .fsproj
+        /// </summary>
+        public const string PROJECT_FS = "{F2A71F9B-5D33-465A-A702-920D77279786}";
+
+        /// <summary>
+        /// .vbproj
+        /// </summary>
+        public const string PROJECT_VB = "{F184B08F-C81C-45F6-A57F-5ABD9991F28F}";
+
+        /// <summary>
+        /// .vcxproj
+        /// </summary>
+        public const string PROJECT_VC = "{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}";
+
+        /// <summary>
+        /// .vjsproj
+        /// </summary>
+        public const string PROJECT_VJ = "{E6FDF86B-F3D1-11D4-8576-0002A516ECE8}";
+
+        /// <summary>
+        /// .wdproj
+        /// </summary>
+        public const string PROJECT_WD = "{2CFEAB61-6A3B-4EB8-B523-560B4BEEF521}";
+
+        /// <summary>
+        /// 
+        /// </summary>
+        public const string PROJECT_WEB = "{E24C65DC-7377-472B-9ABA-BC803B73C61A}";
+
+        /// <summary>
+        /// .deployproj
+        /// </summary>
         public const string PROJECT_DEPLOY = "{151D2E53-A2C4-4D7D-83FE-D05416EBD58E}";
-        public const string PROJECT_SF     = "{A07B5EB6-E848-4116-A8D0-A826331D98C6}";
 
-        private static Dictionary<ProjectType, string> ProjectTypeGuids = new Dictionary<ProjectType, string>()
+        /// <summary>
+        /// .sfproj
+        /// </summary>
+        public const string PROJECT_SF = "{A07B5EB6-E848-4116-A8D0-A826331D98C6}";
+
+        private static Dictionary<ProjectType, string> projectTypeGuids = new Dictionary<ProjectType, string>()
         {
             { ProjectType.Cs, PROJECT_CS },
             { ProjectType.Db, PROJECT_DB },
@@ -70,7 +110,7 @@ public static class Guids
         /// <returns></returns>
         public static ProjectType ProjectTypeBy(string guid)
         {
-            return ProjectTypeGuids.FirstOrDefault(p => p.Value == guid).Key;
+            return projectTypeGuids.FirstOrDefault(p => p.Value == guid).Key;
         }
 
         /// <summary>
@@ -80,7 +120,7 @@ public static ProjectType ProjectTypeBy(string guid)
         /// <returns></returns>
         public static string GuidBy(ProjectType type)
         {
-            return ProjectTypeGuids[type];
+            return projectTypeGuids.GetOrDefault(type);
         }
     }
 }

MvsSln/Core/IConfPlatform.cs

@@ -33,20 +33,38 @@ public interface IConfPlatform
         IRuleOfConfig Rule { get; }
 
         /// <summary>
-        /// To use virtual `Sensitivity` method to compare objects.
+        /// To use an `Sensitivity` logic when comparing {IConfPlatform}
+        /// together with `==` , `!=`.
         /// </summary>
         bool SensitivityComparing { get; set; }
 
         string Configuration { get; }
 
         string ConfigurationByRule { get; }
 
+        /// <summary>
+        /// {ConfigurationByRule} with optional case insensitive logic.
+        /// Uses {SensitivityComparing} flag.
+        /// </summary>
         string ConfigurationByRuleICase { get; }
 
         string Platform { get; }
 
         string PlatformByRule { get; }
 
+        /// <summary>
+        /// {PlatformByRule} with optional case insensitive logic.
+        /// Uses {SensitivityComparing} flag.
+        /// </summary>
         string PlatformByRuleICase { get; }
+
+        /// <summary>
+        /// Checking an config/platform by using {Rule} instance.
+        /// </summary>
+        /// <param name="config">Configuration name.</param>
+        /// <param name="platform">Platform name.</param>
+        /// <param name="icase">Case insensitive flag.</param>
+        /// <returns></returns>
+        bool IsEqualByRule(string config, string platform, bool icase = false);
     }
 }

MvsSln/Core/ISlnResult.cs

@@ -34,6 +34,11 @@ public interface ISlnResult
         /// </summary>
         string SolutionDir { get; }
 
+        /// <summary>
+        /// Full path to an solution file.
+        /// </summary>
+        string SolutionFile { get; }
+
         /// <summary>
         /// Processed type for result.
         /// </summary>
@@ -81,6 +86,7 @@ public interface ISlnResult
 
         /// <summary>
         /// All available global properties for solution.
+        /// Use optional {PropertyNames} to access to popular properties.
         /// </summary>
         RoProperties Properties { get; }
 

MvsSln/Core/IXProjectEnv.cs

@@ -30,6 +30,7 @@
 
 namespace net.r_eg.MvsSln.Core
 {
+    // TODO: typo, add Get+ prefix for all XProjectBy...(), ie. GetXProjectBy...()
     [Guid("1BED7620-25A0-4FC3-BD44-A284782CA68A")]
     public interface IXProjectEnv
     {
@@ -45,15 +46,23 @@ public interface IXProjectEnv
         IEnumerable<IXProject> Projects { get; }
 
         /// <summary>
-        /// List of evaluated projects that filtered by Guid.
+        /// List of evaluated projects that was filtered by Guid.
         /// </summary>
         IEnumerable<IXProject> UniqueByGuidProjects { get; }
 
         /// <summary>
-        /// Access to GlobalProjectCollection
+        /// Access to global Microsoft.Build.Evaluation.ProjectCollection.
+        /// Only if you know what you're doing.
         /// </summary>
         ProjectCollection PrjCollection { get; }
 
+        /// <summary>
+        /// List of valid projects from {PrjCollection}.
+        /// Such as something except `.user` but contains FirstChild / LastChild XML node.
+        /// Only if you know what you're doing.
+        /// </summary>
+        IEnumerable<Project> ValidProjects { get; }
+
         /// <summary>
         /// Find project by Guid.
         /// </summary>
@@ -69,6 +78,31 @@ public interface IXProjectEnv
         /// <returns></returns>
         IXProject[] XProjectsByGuid(string guid);
 
+        /// <summary>
+        /// Find project by full path to file.
+        /// </summary>
+        /// <param name="file">Full path to file.</param>
+        /// <param name="cfg">Specified configuration.</param>
+        /// <param name="tryLoad">Try to load if not found in current project collection.</param>
+        /// <returns></returns>
+        IXProject XProjectByFile(string file, IConfPlatform cfg, bool tryLoad = false);
+
+        /// <summary>
+        /// Find or load project by full path to file.
+        /// </summary>
+        /// <param name="file">Full path to file.</param>
+        /// <param name="cfg">Specified configuration.</param>
+        /// <param name="props">Optional properties when loading or null.</param>
+        /// <returns></returns>
+        IXProject XProjectByFile(string file, IConfPlatform cfg, IDictionary<string, string> props);
+
+        /// <summary>
+        /// Find project by full path to file.
+        /// </summary>
+        /// <param name="file">Full path to file.</param>
+        /// <returns></returns>
+        IEnumerable<IXProject> XProjectsByFile(string file);
+
         /// <summary>
         /// Find projects by name.
         /// </summary>
@@ -85,25 +119,25 @@ public interface IXProjectEnv
         IXProject[] XProjectsByName(string name);
 
         /// <summary>
-        /// Get or firstly load into collection the project. 
-        /// Use default configuration.
+        /// Get or load project using global collection.
+        /// Uses default configuration.
         /// </summary>
         /// <param name="pItem">Specific project.</param>
         /// <returns></returns>
         Project GetOrLoadProject(ProjectItem pItem);
 
         /// <summary>
-        /// Get or firstly load into collection the project.
+        /// Get or load project using global collection.
         /// </summary>
-        /// <param name="pItem">Specific project.</param>
-        /// <param name="conf">Configuration of project to load.</param>
+        /// <param name="pItem">Specified project.</param>
+        /// <param name="cfg">Configuration of project to load.</param>
         /// <returns></returns>
-        Project GetOrLoadProject(ProjectItem pItem, IConfPlatform conf);
+        Project GetOrLoadProject(ProjectItem pItem, IConfPlatform cfg);
 
         /// <summary>
-        /// Get or firstly load into collection the project.
+        /// Get or load project using global collection.
         /// </summary>
-        /// <param name="pItem">Specific project.</param>
+        /// <param name="pItem">Specified project.</param>
         /// <param name="properties"></param>
         /// <returns></returns>
         Project GetOrLoadProject(ProjectItem pItem, IDictionary<string, string> properties);
@@ -120,7 +154,7 @@ public interface IXProjectEnv
         /// Load available projects via configurations.
         /// It will be added without unloading of previous.
         /// </summary>
-        /// <param name="pItems">Specific list or null value to load all available.</param>
+        /// <param name="pItems">Specified list or null value to load all available.</param>
         /// <returns>Loaded projects.</returns>
         IEnumerable<IXProject> LoadProjects(IEnumerable<ProjectItemCfg> pItems = null);
 
@@ -129,5 +163,41 @@ public interface IXProjectEnv
         /// </summary>
         /// <returns>Loaded projects.</returns>
         IEnumerable<IXProject> LoadMinimalProjects();
+
+        /// <summary>
+        /// Assign an existing `Microsoft.Build.Evaluation.Project` instances for local collection.
+        /// </summary>
+        /// <param name="projects">Will use {ValidProjects} if null.</param>
+        /// <returns></returns>
+        IEnumerable<IXProject> Assign(IEnumerable<Project> projects = null);
+
+        /// <summary>
+        /// Adds `Microsoft.Build.Evaluation.Project` instance into IXProject collection if it does not exist.
+        /// </summary>
+        /// <param name="project"></param>
+        /// <returns></returns>
+        IXProject AddOrGet(Project project);
+
+        /// <summary>
+        /// Prepares data from `Microsoft.Build.Evaluation.Project` instance.
+        /// </summary>
+        /// <param name="project"></param>
+        /// <returns></returns>
+        ProjectItemCfg ExtractItemCfg(Project project);
+
+        /// <summary>
+        /// Unloads all evaluated projects at current time.
+        /// Decreases `IXProjectEnv.Projects` collection.
+        /// </summary>
+        /// <param name="throwIfErr">When true, may throw exception if some project cannot be unloaded by some reason.</param>
+        void UnloadAll(bool throwIfErr = true);
+
+        /// <summary>
+        /// Unloads specified project.
+        /// Decreases `IXProjectEnv.Projects` collection.
+        /// </summary>
+        /// <param name="xp"></param>
+        /// <returns>False if project was not unloaded by some reason. Otherwise true.</returns>
+        bool Unload(IXProject xp);
     }
 }