/// <summary>
        /// Overloaded constructor for creating a ComReferenceNode from selector data
        /// </summary>
        /// <param name="root">The Project node</param>
        /// <param name="selectorData">The component selctor data.</param>
        public ComReferenceNode(ProjectNode root, VSCOMPONENTSELECTORDATA selectorData)
            : base(root)
        {
            if (root == null)
            {
                throw new ArgumentNullException("root");
            }
            if (selectorData.type == VSCOMPONENTTYPE.VSCOMPONENTTYPE_Project
                || selectorData.type == VSCOMPONENTTYPE.VSCOMPONENTTYPE_ComPlus)
            {
                throw new ArgumentException();
            }

            // Initialize private state
            this.typeName = selectorData.bstrTitle;
            this.typeGuid = selectorData.guidTypeLibrary;
            this.majorVersionNumber = selectorData.wTypeLibraryMajorVersion.ToString(CultureInfo.InvariantCulture);
            this.minorVersionNumber = selectorData.wTypeLibraryMinorVersion.ToString(CultureInfo.InvariantCulture);
            this.lcid = selectorData.lcidTypeLibrary.ToString(CultureInfo.InvariantCulture);

            // Check to see if the COM object actually exists.
            this.SetInstalledFilePath();
            // If the value cannot be set throw.
            if (String.IsNullOrEmpty(this.installedFilePath))
            {
                throw new ArgumentException();
            }
        }

        /// <summary>
        /// Creates a file reference from the selector data.
        /// </summary>
        protected override ReferenceNode CreateFileComponent(VSCOMPONENTSELECTORDATA selectorData, string wrapperTool = null)
        {
            if(null == selectorData.bstrFile)
                throw new ArgumentNullException("selectorData");

            if( !File.Exists( selectorData.bstrFile ) )
                throw new FileNotFoundException( selectorData.bstrFile );

            return new ApplicationReferenceNode( this.ProjectMgr, selectorData.bstrFile );
        }

        internal virtual ReferenceNode CreateReferenceNode(VSCOMPONENTSELECTORDATA selectorData)
        {
            ReferenceNode node = null;
            switch (selectorData.type)
            {
                case VSCOMPONENTTYPE.VSCOMPONENTTYPE_Project:
                    node = this.CreateProjectReferenceNode(selectorData);
                    EnableCachingForProjectReferencesInBatchUpdate(node);
                    break;
                case VSCOMPONENTTYPE.VSCOMPONENTTYPE_File:
                    node = this.CreateFileComponent(selectorData, AddReferenceDialogTab.BrowseTab);
                    break;
                case VSCOMPONENTTYPE.VSCOMPONENTTYPE_ComPlus:
                    node = this.CreateFileComponent(selectorData, AddReferenceDialogTab.DotNetTab);
                    break;
                case VSCOMPONENTTYPE.VSCOMPONENTTYPE_Com2:
                    node = this.CreateComReferenceNode(selectorData);
                    break;
            }

            return node;
        }

 /// <summary>
 /// Exposed for derived classes to re-enable reference support.
 /// </summary>
 protected ReferenceNode BaseCreateReferenceNode(ref VSCOMPONENTSELECTORDATA selectorData)
 {
     return base.CreateReferenceNode(selectorData);
 }

        /// <summary>
        /// Adds a reference to this container using the selector data structure to identify it.
        /// </summary>
        /// <param name="selectorData">data describing selected component</param>
        /// <returns>Reference in case of a valid reference node has been created or already existed. Otherwise null</returns>
        public ReferenceNode AddReferenceFromSelectorData(VSCOMPONENTSELECTORDATA selectorData)
        {
            //Make sure we can edit the project file
            if (!this.ProjectMgr.QueryEditProjectFile(false))
            {
                throw Marshal.GetExceptionForHR(VSConstants.OLE_E_PROMPTSAVECANCELLED);
            }

            //Create the reference node
            ReferenceNode node = null;
            try
            {
                node = CreateReferenceNode(selectorData);
            }
            catch (ArgumentException)
            {
                // Some selector data was not valid. 
            }

            //Add the reference node to the project if we have a valid reference node
            if (node != null)
            {
                ReferenceNode existingNode;
                if (!node.IsAlreadyAdded(out existingNode))
                {
                    // Try to add
                    node.AddReference();
                    if (null == node.Parent)
                    {
                        // The reference was not added, so we can not return this item because it
                        // is not inside the project.
                        return null;
                    }
                }
                else
                {
                    IVsDetermineWizardTrust wizardTrust = this.GetService(typeof(SVsDetermineWizardTrust)) as IVsDetermineWizardTrust;
                    var isWizardRunning = 0;
                    if (wizardTrust != null)
                    {
                        ErrorHandler.ThrowOnFailure(wizardTrust.IsWizardRunning(out isWizardRunning));
                    }

                    // if assembly already exists in project and we are running under the wizard - do not raise error
                    if (isWizardRunning != 0)
                    {
                        return existingNode;
                    }
                    else
                    {
                        string message = string.IsNullOrEmpty(node.SimpleName) 
                            ? String.Format(CultureInfo.CurrentCulture, SR.GetString(SR.ReferenceAlreadyExists, CultureInfo.CurrentUICulture), node.Caption, existingNode.Caption)
                            : String.Format(CultureInfo.CurrentCulture, SR.GetString(SR.ReferenceWithAssemblyNameAlreadyExists, CultureInfo.CurrentUICulture), node.Caption, node.SimpleName, existingNode.Caption);
                        throw new InvalidOperationException(message);
                    }
                }
            }

            return node;
        }

 public int AddBrowseContainer(VSCOMPONENTSELECTORDATA[] pcdComponent, ref uint pgrfOptions, out string pbstrComponentAdded)
 {
     throw new NotImplementedException();
 }

        /// <summary>
        /// Creates an assemby or com reference node given a selector data.
        /// </summary>
        protected virtual ReferenceNode CreateFileComponent(VSCOMPONENTSELECTORDATA selectorData) {
            if (null == selectorData.bstrFile) {
                throw new ArgumentNullException("selectorData");
            }

            // We have a path to a file, it could be anything
            // First see if it is a managed assembly
            bool tryToCreateAnAssemblyReference = true;
            if (File.Exists(selectorData.bstrFile)) {
                try {
                    // We should not load the assembly in the current appdomain.
                    // If we do not do it like that and we load the assembly in the current appdomain then the assembly cannot be unloaded again. 
                    // The following problems might arose in that case.
                    // 1. Assume that a user is extending the MPF and  his project is creating a managed assembly dll.
                    // 2. The user opens VS and creates a project and builds it.
                    // 3. Then the user opens VS creates another project and adds a reference to the previously built assembly. This will load the assembly in the appdomain had we been using Assembly.ReflectionOnlyLoadFrom.
                    // 4. Then he goes back to the first project modifies it an builds it. A build error is issued that the assembly is used.

                    // GetAssemblyName is assured not to load the assembly.
                    tryToCreateAnAssemblyReference = (AssemblyName.GetAssemblyName(selectorData.bstrFile) != null);
                } catch (BadImageFormatException) {
                    // We have found the file and it is not a .NET assembly; no need to try to
                    // load it again.
                    tryToCreateAnAssemblyReference = false;
                } catch (FileLoadException) {
                    // We must still try to load from here because this exception is thrown if we want 
                    // to add the same assembly refererence from different locations.
                    tryToCreateAnAssemblyReference = true;
                }
            }

            ReferenceNode node = null;

            if (tryToCreateAnAssemblyReference) {
                // This might be a candidate for an assembly reference node. Try to load it.
                // CreateAssemblyReferenceNode will suppress BadImageFormatException if the node cannot be created.
                node = this.CreateAssemblyReferenceNode(selectorData.bstrFile);
            }

            // If no node has been created try to create a com reference node.
            if (node == null) {
                if (!File.Exists(selectorData.bstrFile)) {
                    return null;
                }

                node = ProjectMgr.CreateReferenceNodeForFile(selectorData.bstrFile);
            }

            return node;
        }

 /// <summary>
 /// Create a Project to Project reference given a VSCOMPONENTSELECTORDATA structure
 /// </summary>
 protected override ProjectReferenceNode CreateProjectReferenceNode(
   VSCOMPONENTSELECTORDATA selectorData)
 {
     return new SandcastleBuilderProjectReferenceNode(this.ProjectMgr,
         selectorData.bstrTitle, selectorData.bstrFile, selectorData.bstrProjRef);
 }

        private string GetComponentPickerDirectories()
        {
            IVsComponentEnumeratorFactory4 enumFactory = this.site.GetService(typeof(SCompEnumService)) as IVsComponentEnumeratorFactory4;
            if (enumFactory == null)
            {
                throw new InvalidOperationException("Missing the SCompEnumService service.");
            }

            IEnumComponents enumerator;
            Marshal.ThrowExceptionForHR(enumFactory.GetReferencePathsForTargetFramework(this.TargetFrameworkMoniker.FullName, out enumerator));
            if (enumerator == null)
            {
                throw new ApplicationException("IVsComponentEnumeratorFactory4.GetReferencePathsForTargetFramework returned null.");
            }

            StringBuilder paths = new StringBuilder();
            VSCOMPONENTSELECTORDATA[] data = new VSCOMPONENTSELECTORDATA[1];
            uint fetchedCount;
            while (enumerator.Next(1, data, out fetchedCount) == VSConstants.S_OK && fetchedCount == 1)
            {
                Debug.Assert(data[0].type == VSCOMPONENTTYPE.VSCOMPONENTTYPE_Path);
                paths.Append(data[0].bstrFile);
                paths.Append(";");
            }

            // Trim off the last semicolon.
            if (paths.Length > 0)
            {
                paths.Length -= 1;
            }

            return paths.ToString();
        }

 /// <include file='doc\Hierarchy.uex' path='docs/doc[@for="HierarchyNode.AddComponent"]/*' />
 /// <summary>
 /// Add Component of the IVsComponentUser interface
 /// it serves as a callback from IVsComponentSelector dialog
 /// to notify us when a component was added as a reference to the project
 /// - needs to update the persistence data here.
 /// </summary>
 public virtual int AddComponent(VSADDCOMPOPERATION dwAddCompOperation, uint cComponents, System.IntPtr[] rgpcsdComponents, System.IntPtr hwndDialog, VSADDCOMPRESULT[] pResult){
   try{
     for (int cCount = 0; cCount < cComponents; cCount++){
       VSCOMPONENTSELECTORDATA selectorData = new VSCOMPONENTSELECTORDATA();
       IntPtr ptr = rgpcsdComponents[cCount];
       selectorData = (VSCOMPONENTSELECTORDATA)Marshal.PtrToStructure(ptr, typeof(VSCOMPONENTSELECTORDATA));
       this.projectMgr.AddReference(selectorData);
     }
   }catch{}
   pResult[0] = VSADDCOMPRESULT.ADDCOMPRESULT_Success;
   return 0;
 }

        /// <summary>
        /// Adds a reference to this container using the selector data structure to identify it.
        /// </summary>
        /// <param name="selectorData">data describing selected component</param>
        /// <param name="wrapperTool">Wrapper tool</param>
        /// <returns>Reference in case of a valid reference node has been created. Otherwise null</returns>
        public ReferenceNode AddReferenceFromSelectorData(VSCOMPONENTSELECTORDATA selectorData, string wrapperTool = null)
        {
            //Make sure we can edit the project file
            if(!this.ProjectMgr.QueryEditProjectFile(false))
            {
                throw Marshal.GetExceptionForHR(VSConstants.OLE_E_PROMPTSAVECANCELLED);
            }

            //Create the reference node
            ReferenceNode node = null;
            try
            {
                node = CreateReferenceNode(selectorData, wrapperTool);
            }
            catch(ArgumentException)
            {
                // Some selector data was not valid. 
            }

            // Does such a reference already exist in the project?
            ReferenceNode existingNode;
            if (node.IsAlreadyAdded(out existingNode))
            {
                return existingNode;
            }

            //Add the reference node to the project if we have a valid reference node
            if(node != null)
            {
                // This call will find if the reference is in the project and, in this case
                // will not add it again, so the parent node will not be set.
                node.AddReference();
                if(null == node.Parent)
                {
                    // The reference was not added, so we can not return this item because it
                    // is not inside the project.
                    return null;
                }
            }

            return node;
        }

        /// <summary>
        /// This is overridden to handle file references correctly when added to the project
        /// </summary>
        /// <inheritdoc />
        public override int AddComponent(VSADDCOMPOPERATION dwAddCompOperation, uint cComponents,
           IntPtr[] rgpcsdComponents, IntPtr hwndDialog, VSADDCOMPRESULT[] pResult)
        {
            if(rgpcsdComponents == null || pResult == null)
                return VSConstants.E_FAIL;

            // Initialize the out parameter
            pResult[0] = VSADDCOMPRESULT.ADDCOMPRESULT_Success;

            IReferenceContainer references = GetReferenceContainer();

            if(null == references)
            {
                // This project does not support references or the reference container was not created.
                // In both cases this operation is not supported.
                return VSConstants.E_NOTIMPL;
            }

            for(int cCount = 0; cCount < cComponents; cCount++)
            {
                VSCOMPONENTSELECTORDATA selectorData = new VSCOMPONENTSELECTORDATA();
                IntPtr ptr = rgpcsdComponents[cCount];
                selectorData = (VSCOMPONENTSELECTORDATA)Marshal.PtrToStructure(ptr, typeof(VSCOMPONENTSELECTORDATA));

                var node = references.AddReferenceFromSelectorData(selectorData);

                if(node == null)
                {
                    // Skip further processing since a reference has to be added
                    pResult[0] = VSADDCOMPRESULT.ADDCOMPRESULT_Failure;
                    return VSConstants.S_OK;
                }

                // If it's a file, get rid of the Name and AssemblyName metadata and add the HintPath metadata.
                // If not, when the project is opened the next time, the reference will appear as missing
                // if it isn't in the GAC.
                if(node != null && selectorData.type == VSCOMPONENTTYPE.VSCOMPONENTTYPE_File)
                {
                    string hintPath = selectorData.bstrFile;

                    if(Path.IsPathRooted(hintPath))
                        hintPath = PackageUtilities.GetPathDistance(this.ProjectMgr.BaseURI.Uri, new Uri(hintPath));

                    node.ItemNode.SetMetadata(ProjectFileConstants.Name, null);
                    node.ItemNode.SetMetadata(ProjectFileConstants.AssemblyName, null);
                    node.ItemNode.SetMetadata(ProjectFileConstants.HintPath, hintPath);
                }

            }

            return VSConstants.S_OK;
        }

        public override int OnAfterRenameProject(IVsHierarchy hierarchy)
        {
            if (hierarchy == null)
            {
                return VSConstants.E_INVALIDARG;
            }

            try
            {
                var projectReferences = GetProjectReferencesContainingThisProject(hierarchy);

                // Collect data that is needed to initialize the new project reference node.
                string projectRef;
                ErrorHandler.ThrowOnFailure(Solution.GetProjrefOfProject(hierarchy, out projectRef));

                object nameAsObject;
                ErrorHandler.ThrowOnFailure(hierarchy.GetProperty(VSConstants.VSITEMID_ROOT,
                    (int) __VSHPROPID.VSHPROPID_Name, out nameAsObject));
                var projectName = (string) nameAsObject;

                var projectPath = string.Empty;

                var project = hierarchy as IVsProject3;

                if (project != null)
                {
                    ErrorHandler.ThrowOnFailure(project.GetMkDocument(VSConstants.VSITEMID_ROOT, out projectPath));
                    projectPath = Path.GetDirectoryName(projectPath);
                }

                // Remove and re add the node.
                foreach (var projectReference in projectReferences)
                {
                    var projectMgr = projectReference.ProjectMgr;
                    var refContainer = projectMgr.GetReferenceContainer();
                    projectReference.Remove(false);

                    var selectorData = new VSCOMPONENTSELECTORDATA();
                    selectorData.type = VSCOMPONENTTYPE.VSCOMPONENTTYPE_Project;
                    selectorData.bstrTitle = projectName;
                    selectorData.bstrFile = projectPath;
                    selectorData.bstrProjRef = projectRef;
                    refContainer.AddReferenceFromSelectorData(selectorData);
                }
            }
            catch (COMException e)
            {
                return e.ErrorCode;
            }

            return VSConstants.S_OK;
        }

            /// <devdoc>
            ///     Moves to the next element. This returns false if we are at the end or are otherwise unable
            ///     to move.
            /// </devdoc>
            bool IEnumerator.MoveNext() {
                
                currentName = null;
                string fileName = null;
                
                // If we've already cached this guy once, use the cached data.
                //
                if (cachedNames != null && current < cachedNames.Count - 1) {
                    current++;
                    currentName = (AssemblyName)cachedNames[current];
                    Debug.Assert(currentName != null, "cache is bunk.");
                    return true;
                }

                // We normally only will loop through this while once.  The only time we will
                // go through it more than once is when we discover a file, and that file is an
                // invalid assembly.
                while (fileName == null 
                    ||  currentName == null /* SBurke -- workaround for CLR bug # VSWhidbey 211103, but it might be worth leaving in here anyway */) {
                    if (name == null) {
                        // No specific name, so match all components.  Note that this is really slow -- VS takes forever
                        // to calculate this.
                        //
                        if (componentEnum == null) {
                            NativeMethods.ThrowOnFailure( enumFactory.GetComponents(null, (int)CompEnum.CompEnumType_COMPlus, 0, out componentEnum) );
                            selector = new VSCOMPONENTSELECTORDATA[1];
                            selector[0] = new VSCOMPONENTSELECTORDATA();
                            selector[0].dwSize = (uint)Marshal.SizeOf(typeof(VSCOMPONENTSELECTORDATA));
                        }
                        
                        uint fetched;
                        NativeMethods.ThrowOnFailure( componentEnum.Next(1, selector, out fetched) );
                        
                        if (fetched == 0) {
                            return false;
                        }
                        
                        Debug.Assert(selector[0].type == VSCOMPONENTTYPE.VSCOMPONENTTYPE_ComPlus, "Asked for CLR components but didn't get 'em.");
                        fileName = selector[0].bstrFile;
                    }
                    else {
                        // We were given a specific name to match.  Do a path based reference on sdk paths and
                        // then match files within that path.
                        // 
                        if (componentEnum == null) {
                            NativeMethods.ThrowOnFailure( enumFactory.GetComponents(null, (int)CompEnum.CompEnumType_AssemblyPaths, 0, out componentEnum) );
                            selector = new VSCOMPONENTSELECTORDATA[1];
                            selector[0] = new VSCOMPONENTSELECTORDATA();
                            selector[0].dwSize = (uint)Marshal.SizeOf(typeof(VSCOMPONENTSELECTORDATA));
                        }
                        
                        while(true) {
                            uint fetched;
                            NativeMethods.ThrowOnFailure( componentEnum.Next(1, selector, out fetched) );
                            
                            if (fetched == 0) {
                                return false;
                            }
                            
                            Debug.Assert(selector[0].type == VSCOMPONENTTYPE.VSCOMPONENTTYPE_Path, "Asked for sdk paths but didn't get 'em.");
                            string assemblyPath = Path.Combine(selector[0].bstrFile, name);
                            if (File.Exists(assemblyPath)) {
                                fileName = assemblyPath;
                                break;
                            }
                        }
                    }
                    
                    Debug.Assert(fileName != null, "We should have always retrieved a file name here.");

                    try {
                        currentName = AssemblyName.GetAssemblyName(fileName);
                    }
                    catch(FileLoadException) {
                        // This file is invalid.  Null the name so we continue our loop.
                        fileName = null;
                    }
                    catch(BadImageFormatException) {
                        // This file is invalid.  Null the name so we continue our loop.
                        fileName = null;
                    }
                }
                
                // Store this assembly name in our cache, because they're quite expensive to get.
                //
                if (cachedNames == null) {
                    cachedNames = new ArrayList();
                }
                
                cachedNames.Add(currentName);
                current++;
                
                return true;
            }

 protected virtual ReferenceNode CreateReferenceNode(VSCOMPONENTSELECTORDATA selectorData)
 {
     return CreateReferenceNode(selectorData, null);
 }

 /// <summary>
 /// Adds a reference to this container using the selector data structure to identify it.
 /// </summary>
 /// <param name="selectorData">data describing selected component</param>
 /// <returns>Reference in case of a valid reference node has been created. Otherwise null</returns>
 public virtual ReferenceNode AddReferenceFromSelectorData(VSCOMPONENTSELECTORDATA selectorData)
 {
     return AddReferenceFromSelectorData(selectorData, null);
 }

        /// <summary>
        /// Creates an assemby or com reference node given a selector data.
        /// </summary>
        internal virtual ReferenceNode CreateFileComponent(VSCOMPONENTSELECTORDATA selectorData, AddReferenceDialogTab tab)
        {
            if (null == selectorData.bstrFile)
            {
                throw new ArgumentNullException("selectordata.bstrFile");
            }

            // Support the "*<assemblyName>" format that Cider uses
            if (selectorData.bstrFile.StartsWith("*"))
            {
                var assemblyNameStr = selectorData.bstrFile.Substring(1);
                return this.CreateAssemblyReferenceNode(assemblyNameStr, tab, false /*isFullPath*/);
            }

            ReferenceNode node = null;

            try
            {
                node = this.CreateAssemblyReferenceNode(selectorData.bstrFile, tab, true);
            }
            catch(InvalidOperationException)
            {
                // If the selector doesn't have a guid, it means we didn't go through the COM tab. This means
                // that we are either adding a reference via automation, or manually browsing to a TLB.
                if (selectorData.guidTypeLibrary == Guid.Empty)
                {
                    try
                    {
                        node = this.CreateComReferenceNode(selectorData.bstrFile);
                    }
                    catch (COMException)
                    {
                        // Ignore all the TLB exceptions
                    }
                }
                else
                {
                    node = this.CreateComReferenceNode(selectorData);
                }
            }

            if (node == null)
            {
                this.ProjectMgr.AddReferenceCouldNotBeAddedErrorMessage(selectorData.bstrFile);
            }

            return node;
        }

 protected override ProjectReferenceNode CreateProjectReferenceNode(VSCOMPONENTSELECTORDATA selectorData) {
     return new PythonProjectReferenceNode(ProjectMgr, selectorData.bstrTitle, selectorData.bstrFile, selectorData.bstrProjRef);
 }

 /// <summary>
 /// Creates a com reference node from a selector data.
 /// </summary>
 /// <returns>A COM reference node</returns>
 protected override ComReferenceNode CreateComReferenceNode(VSCOMPONENTSELECTORDATA selectorData,
   string wrapperTool = null)
 {
     return new SandcastleBuilderComReferenceNode(this.ProjectMgr, selectorData);
 }

 public int AddBrowseContainer(
     VSCOMPONENTSELECTORDATA[] pcdComponent, ref uint pgrfOptions, out string pbstrComponentAdded)
 {
     pbstrComponentAdded = null;
     return VSConstants.E_NOTIMPL;
 }