Add async methods for C# source code retrieval

Introduce `FindCSharpSourceCodeAsync` methods in
`IVsProjectActions`, `IVsProjectFolderActions`,
`VsProject`, and `VsProjectFolder` for searching
C# source code files with customizable criteria.

Add new classes `CsSearchContainer` and
`CsSourceSearchCriteria` to model search results
and criteria. Update using directives for integration.

Author: sgiffinlcd

Src/CodeFactoryForWindows/CodeFactory.WinVs/Models/CSharp/CsSearchContainer.cs

@@ -0,0 +1,99 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Text;
+
+namespace CodeFactory.WinVs.Models.CSharp
+{
+    /// <summary>
+    /// Data model that represents a summary of a C# container (class, interface, structure, etc.) for search results.
+    /// </summary>
+    public class CsSearchContainer
+    {
+        /// <summary>
+        /// The namespace the C# cntainer is defined in.
+        /// </summary>
+        public string Namespace { get; init; }
+
+        /// <summary>
+        /// Gets the name of the container associated with the current instance.
+        /// </summary>
+        public string Name { get; init; }
+
+        /// <summary>
+        /// The security scope of the container represented by this instance.
+        /// </summary>
+        CsSecurity Security { get; init; } = CsSecurity.Unknown;
+
+        /// <summary>
+        /// Gets the type of the container represented by this instance.
+        /// </summary>
+        public CsContainerType ContainerType { get; init; } = CsContainerType.Unknown;
+
+        /// <summary>
+        /// Flag that determines if this container has a generic type definition.
+        /// </summary>
+        public bool IsGenericContainer { get; init; } = false;
+
+        /// <summary>
+        /// List of the generic parameters defined for the container.
+        /// </summary>
+        public IReadOnlyList<CsGenericParameter> GenericParameters { get; init; } = ImmutableList<CsGenericParameter>.Empty;
+
+        /// <summary>
+        /// Flag that determines if the container has strong types defined in its generic parameters.
+        /// </summary>
+        public bool HasStrongTypesInGenerics { get; init; } = false;
+
+        /// <summary>
+        /// List of the generic types defined for the container.
+        /// </summary>
+        public IReadOnlyList<CsType> GenericTypes { get; init; } = ImmutableList<CsType>.Empty;
+
+        /// <summary>
+        /// Flag that determines if the container has a base class defined.
+        /// </summary>
+        public bool HasBaseClass { get; init; } = false;
+
+        /// <summary>
+        /// Flag that determines if the container inherits from any interfaces.
+        /// </summary>
+        public bool HasInheritedInterfaces { get; init; } = false;
+
+        /// <summary>
+        /// Flag that determines if the container has any attributes defined.
+        /// </summary>
+        public bool HasAttributes { get; init; } = false;
+
+        /// <summary>
+        /// List of the attributes defined for the container.
+        /// </summary>
+        public IReadOnlyList<CsAttribute> Attributes { get; init; } = ImmutableList<CsAttribute>.Empty;
+
+        /// <summary>
+        /// Flag that determines if the container has any fields defined.
+        /// </summary>
+        public bool HasFields { get; init; } = false;
+
+        /// <summary>
+        /// Flag that determines if the container has any properties defined.
+        /// </summary>
+        public bool HasProperties { get; init; } = false;
+
+        /// <summary>
+        /// Flag that determines if the container has any methods defined.
+        /// </summary>
+        public bool HasMethods { get; init; } = false;
+
+        /// <summary>
+        /// Flag that determines if the container has any events defined.
+        /// </summary>
+        public bool HasEvents { get; init; } = false;
+
+        /// <summary>
+        /// Flag that determines if the container has any constructors defined.
+        /// </summary>
+        public bool HasConstructors { get; init; } = false;
+
+    }
+}

Src/CodeFactoryForWindows/CodeFactory.WinVs/Models/CSharp/CsSourceSearchCriteria.cs

@@ -0,0 +1,59 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace CodeFactory.WinVs.Models.CSharp
+{
+    /// <summary>
+    /// Represents a set of search criteria for locating specific elements within a c# source code file.
+    /// </summary>
+    /// <remarks>This class provides a collection of customizable search predicates that can be used to filter
+    /// and locate various elements within a source code container, such as methods, properties, fields, events,
+    /// constructors, inherited interfaces, and base classes. Each predicate allows the caller to define specific
+    /// conditions for the search, enabling flexible and precise queries.</remarks>
+    public class CsSourceSearchCriteria
+    {
+
+        /// <summary>
+        /// Stores the search criteria for searching for a specific container in the source code.
+        /// </summary>
+        public Func<CsSearchContainer, bool> ContainerSearch { get; init; } = null;
+
+        /// <summary>
+        /// Stores the search criteria for searching for a specific interface in the container.
+        /// </summary>
+        public Func<IReadOnlyList<CsInterface>, bool> InheritedInterfacesSearch { get; init; } = null;
+
+        /// <summary>
+        /// Stores the search criteria for searching methods in the container.
+        /// </summary>
+        public Func<IReadOnlyList<CsMethod>, bool> MethodsSearch { get; init; } = null;
+
+        /// <summary>
+        /// Stores the search criteria for searching properties in the container.
+        /// </summary>
+        public Func<IReadOnlyList<CsProperty>, bool> PropertiesSearch { get; init; } = null;
+
+        /// <summary>
+        /// Stores the search criteria for searching fields in the container.
+        /// </summary>
+        public Func<IReadOnlyList<CsField>, bool> FieldsSearch { get; init; } = null;
+
+        /// <summary>
+        /// Stores the search criteria for searching events in the container.
+        /// </summary>
+        public Func<IReadOnlyList<CsEvent>, bool> EventsSearch { get; init; } = null;
+
+        /// <summary>
+        /// Stores the search criteria for constructors in the container.
+        /// </summary>
+        public Func<IReadOnlyList<CsMethod>, bool> ConstructorsSearch { get; init; } = null;
+
+        /// <summary>
+        /// Stores the search criteria for searching the base class of the container.
+        /// </summary>
+        public Func<CsSearchContainer, bool> BaseSearch { get; init; } = null;
+
+    }
+}

Src/CodeFactoryForWindows/CodeFactory.WinVs/Models/ProjectSystem/IVsProjectActions.cs

@@ -3,6 +3,7 @@
 //* Copyright (c) 2020-2023 CodeFactory, LLC
 //*****************************************************************************
 
+using CodeFactory.WinVs.Models.CSharp;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
@@ -68,5 +69,21 @@ public interface IVsProjectActions
         /// <returns>Readonly list of the referenced projects or an empty list if there is no referenced projects.</returns>
         Task<IReadOnlyList<VsProject>> GetReferencedProjects(VsProject source);
 
+        /// <summary>
+        /// Asynchronously retrieves a collection of source code files from the specified Visual Studio project that
+        /// match the given search criteria.
+        /// </summary>
+        /// <remarks>This method performs an asynchronous search within the provided project and applies
+        /// the specified  search criteria to identify matching source code files. Use the <paramref
+        /// name="IgnoreFolderPaths"/>  parameter to exclude specific folders from the search if needed.</remarks>
+        /// <param name="source">The Visual Studio project to search for source code files.</param>
+        /// <param name="searchCriteria">The criteria used to filter the source code files to be retrieved.</param>
+        /// <param name="searchSubFolders">Flag that determines if sub folders from this location will be searched. Default value is <c>true</c>.</param>
+        /// <param name="IgnoreFolderPaths">An optional collection of folder paths to exclude from the search. If <see langword="null"/>, no folders are
+        /// excluded. When setting the folder paths just include the folder name. If you are going multiple folders deep use a forward slash as the folder seperator.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains a read-only list of  <see
+        /// cref="CsSource"/> objects that match the specified search criteria.</returns>
+        Task<IReadOnlyList<CsSource>> FindCSharpSourceCodeAsync(VsProject source, CsSourceSearchCriteria searchCriteria, bool searchSubFolders = true, IEnumerable<string> IgnoreFolderPaths = null);
+
     }
 }

Src/CodeFactoryForWindows/CodeFactory.WinVs/Models/ProjectSystem/IVsProjectFolderActions.cs

@@ -3,6 +3,7 @@
 //* Copyright (c) 2020-2023 CodeFactory, LLC
 //*****************************************************************************
 
+using CodeFactory.WinVs.Models.CSharp;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
@@ -74,5 +75,21 @@ public interface IVsProjectFolderActions
         /// <param name="source">The project folder model to get the namespace for.</param>
         /// <returns>The fully qualified namespace if the project is a c# project that supports this project folder. Otherwise null will be returned.</returns>
         Task<string> GetCSharpNamespaceAsync(VsProjectFolder source);
+
+        /// <summary>
+        /// Asynchronously retrieves a collection of source code files from the specified Visual Studio project folder that
+        /// match the given search criteria.
+        /// </summary>
+        /// <remarks>This method performs an asynchronous search within the provided project and applies
+        /// the specified  search criteria to identify matching source code files. Use the <paramref
+        /// name="IgnoreFolderPaths"/>  parameter to exclude specific folders from the search if needed.</remarks>
+        /// <param name="source">The Visual Studio project folder to search for source code files.</param>
+        /// <param name="searchCriteria">The criteria used to filter the source code files to be retrieved.</param>
+        /// <param name="searchSubFolders">Flag that determines if sub folders from this location will be searched. Default value is <c>true</c>.</param>
+        /// <param name="IgnoreFolderPaths">An optional collection of folder paths to exclude from the search. If <see langword="null"/>, no folders are
+        /// excluded. When setting the folder paths just include the folder name. If you are going multiple folders deep use a forward slash as the folder seperator.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains a read-only list of  <see
+        /// cref="CsSource"/> objects that match the specified search criteria.</returns>
+        Task<IReadOnlyList<CsSource>> FindCSharpSourceCodeAsync(VsProjectFolder source, CsSourceSearchCriteria searchCriteria, bool searchSubFolders = true, IEnumerable<string> IgnoreFolderPaths = null);
     }
 }

Src/CodeFactoryForWindows/CodeFactory.WinVs/Models/ProjectSystem/VsProject.cs

@@ -3,6 +3,7 @@
 //* Copyright (c) 2020-2023 CodeFactory, LLC
 //*****************************************************************************
 
+using CodeFactory.WinVs.Models.CSharp;
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.Linq;
@@ -152,5 +153,20 @@ public async Task<IReadOnlyList<VsProject>> GetReferencedProjects()
 
             return projects.Any() ? projects.ToImmutableList() : ImmutableList<VsProject>.Empty;
         }
+
+        /// <summary>
+        /// Asynchronously retrieves a collection of source code files from the specified Visual Studio project that
+        /// match the given search criteria.
+        /// </summary>
+        /// <remarks>This method performs an asynchronous search within the provided project and applies
+        /// the specified  search criteria to identify matching source code files. Use the <paramref
+        /// name="IgnoreFolderPaths"/>  parameter to exclude specific folders from the search if needed.</remarks>
+        /// <param name="searchCriteria">The criteria used to filter the source code files to be retrieved.</param>
+        /// <param name="searchSubFolders">Flag that determines if sub folders from this location will be searched. Default value is <c>true</c>.</param>
+        /// <param name="IgnoreFolderPaths">An optional collection of folder paths to exclude from the search. If <see langword="null"/>, no folders are
+        /// excluded. When setting the folder paths just include the folder name. If you are going multiple folders deep use a forward slash as the folder seperator.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains a read-only list of  <see
+        /// cref="CsSource"/> objects that match the specified search criteria.</returns>
+        public abstract Task<IReadOnlyList<CsSource>> FindCSharpSourceCodeAsync(CsSourceSearchCriteria searchCriteria, bool searchSubFolders = true, IEnumerable<string> IgnoreFolderPaths = null);
     }
 }

Src/CodeFactoryForWindows/CodeFactory.WinVs/Models/ProjectSystem/VsProjectFolder.cs

@@ -3,6 +3,7 @@
 //* Copyright (c) 2020-2023 CodeFactory, LLC
 //*****************************************************************************
 
+using CodeFactory.WinVs.Models.CSharp;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
@@ -110,5 +111,20 @@ protected VsProjectFolder(bool isLoaded, bool hasErrors,
         /// </summary>
         /// <returns>The fully qualified namespace if the project is a c# project that supports this project folder. Otherwise null will be returned.</returns>
         public abstract Task<string> GetCSharpNamespaceAsync();
+
+        /// <summary>
+        /// Asynchronously retrieves a collection of source code files from the specified Visual Studio project folder that
+        /// match the given search criteria.
+        /// </summary>
+        /// <remarks>This method performs an asynchronous search within the provided project folder and applies
+        /// the specified  search criteria to identify matching source code files. Use the <paramref
+        /// name="IgnoreFolderPaths"/>  parameter to exclude specific folders from the search if needed.</remarks>
+        /// <param name="searchCriteria">The criteria used to filter the source code files to be retrieved.</param>
+        /// <param name="searchSubFolders">Flag that determines if sub folders from this location will be searched. Default value is <c>true</c>.</param>
+        /// <param name="IgnoreFolderPaths">An optional collection of folder paths to exclude from the search. If <see langword="null"/>, no folders are
+        /// excluded. When setting the folder paths just include the folder name. If you are going multiple folders deep use a forward slash as the folder seperator.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains a read-only list of  <see
+        /// cref="CsSource"/> objects that match the specified search criteria.</returns>
+        public abstract Task<IReadOnlyList<CsSource>> FindCSharpSourceCodeAsync(CsSourceSearchCriteria searchCriteria, bool searchSubFolders = true, IEnumerable<string> IgnoreFolderPaths = null);
     }
 }