/// <summary>
        /// Constructor to create a new MSBuild.ProjectItem and add it to the project
        /// Only have internal constructors as the only one who should be creating
        /// such object is the project itself (see Project.CreateFileNode()).
        /// </summary>
        internal ProjectElement(ProjectNode project, string itemPath, string itemType)
        {
            if(project == null)
            {
                throw new ArgumentNullException("project");
            }

            if(String.IsNullOrEmpty(itemPath))
            {
                throw new ArgumentException(SR.GetString(SR.ParameterCannotBeNullOrEmpty, CultureInfo.CurrentUICulture), "itemPath");
            }

            if(String.IsNullOrEmpty(itemType))
            {
                throw new ArgumentException(SR.GetString(SR.ParameterCannotBeNullOrEmpty, CultureInfo.CurrentUICulture), "itemType");
            }

            this.itemProject = project;

            // create and add the item to the project

            this.item = project.BuildProject.AddItem(itemType, Microsoft.Build.Evaluation.ProjectCollection.Escape(itemPath))[0];
            this.itemProject.SetProjectFileDirty(true);
            this.RefreshProperties();
        }

        /// <summary>
        /// Constructor to Wrap an existing MSBuild.ProjectItem
        /// Only have internal constructors as the only one who should be creating
        /// such object is the project itself (see Project.CreateFileNode()).
        /// </summary>
        /// <param name="project">Project that owns this item</param>
        /// <param name="existingItem">an MSBuild.ProjectItem; can be null if virtualFolder is true</param>
        /// <param name="virtualFolder">Is this item virtual (such as reference folder)</param>
        internal MsBuildProjectElement(ProjectNode project, MSBuild.ProjectItem existingItem)
            : base(project) {
            Utilities.ArgumentNotNull("existingItem", existingItem);

            // Keep a reference to project and item
            _item = existingItem;
        }

        public static bool IsOrphaned(ProjectItem buildItem, ProjectBase owner)
        {
            bool considerBuildItem = (buildItem.ItemType == "Compile" || buildItem.ItemType == "Content" || buildItem.ItemType == "None");

            if(!considerBuildItem)
            {
                if (owner is VisualStudioProject)
                {
                    var asVisualStudioProject = owner as VisualStudioProject;

                    if (!considerBuildItem && buildItem.ItemType == asVisualStudioProject.DefaultContentAction)
                    {
                        considerBuildItem = true;
                    }
                }
            }

            if (considerBuildItem)
            {
                // characters like '%' are encoded, so we have to decode them:
                string relativeName = System.Web.HttpUtility.UrlDecode( buildItem.UnevaluatedInclude);
                string fullName = owner.MakeAbsolute(relativeName);
                return !FileManager.FileExists(fullName) && buildItem.ItemType != "ProjectReference";
            }
            return false;
        }

 private ProjectReferenceAdapter GetProjectReferenceAdapter(ProjectItem r, bool conditionTrue)
 {
     var projectGuid = r.GetMetadataValue("Project");
     var csprojRelativePath = r.EvaluatedInclude;
     var absoluteProjectPath = Path.Combine(ProjectDirectory.FullName, csprojRelativePath);
     var referencedProjectAdapter = _projectLoader.GetProject(Guid.Parse(projectGuid), absoluteProjectPath);
     return new ProjectReferenceAdapter(referencedProjectAdapter, () => _project.RemoveItem(r), AddBinaryReferenceIfNotExists, conditionTrue);
 }

        /// <summary>Loads a <see cref="VsProjectReference"/> from a <see cref="ProjectItem"/>. </summary>
        /// <param name="project">The parent project. </param>
        /// <param name="projectItem">The <see cref="ProjectItem"/>. </param>
        /// <returns>The <see cref="VsProjectReference"/>. </returns>
        public static VsProjectReference Load(VsProject project, ProjectItem projectItem)
        {
            var path = System.IO.Path.Combine(System.IO.Path.GetDirectoryName(project.Path), projectItem.EvaluatedInclude);
            path = System.IO.Path.GetFullPath(path);

            var name = projectItem.Metadata.Single(m => m.Name == "Name").EvaluatedValue;

            return new VsProjectReference(path, name);
        }

        private string _url; // cached Url

        /// <summary>
        /// Constructor to create a new MSBuild.ProjectItem and add it to the project
        /// Only have internal constructors as the only one who should be creating
        /// such object is the project itself (see Project.CreateFileNode()).
        /// </summary>
        internal MsBuildProjectElement(ProjectNode project, string itemPath, string itemType)
            : base(project) {
            Utilities.ArgumentNotNullOrEmpty("itemPath", itemPath);
            Utilities.ArgumentNotNullOrEmpty("itemType", itemType);

            // create and add the item to the project

            _item = project.BuildProject.AddItem(itemType, Microsoft.Build.Evaluation.ProjectCollection.Escape(itemPath))[0];
            _url = base.Url;
        }

        /// <summary>
        /// Constructor to create a new MSBuild.ProjectItem and add it to the project
        /// Only have internal constructors as the only one who should be creating
        /// such object is the project itself (see Project.CreateFileNode()).
        /// </summary>
        internal MsBuildProjectElement(ProjectNode project, string itemPath, string itemType)
            : base(project)
        {
            Utilities.ArgumentNotNullOrEmpty("itemPath", itemPath);
            Utilities.ArgumentNotNullOrEmpty("itemType", itemType);

            // create and add the item to the project

            _item = project.BuildProject.AddItem(itemType, Microsoft.Build.Evaluation.ProjectCollection.Escape(itemPath))[0];
            ItemProject.SetProjectFileDirty(true);
            RefreshProperties();
        }

        public VirtualEnvNode(JProjectNode project, ProjectItem item)
            : base(project, new MsBuildProjectElement(project, item))
        {
            _caption = Path.GetFileName(item.EvaluatedInclude);
            _scheduler = TaskScheduler.FromCurrentSynchronizationContext();

            _fileWatcher = new FileSystemWatcher(CommonUtils.GetAbsoluteDirectoryPath(project.ProjectHome, item.EvaluatedInclude), "*");
            _fileWatcher.IncludeSubdirectories = true;
            _fileWatcher.Deleted += PackagesChanged;
            _fileWatcher.Created += PackagesChanged;
            _fileWatcher.EnableRaisingEvents = true;
            _timer = new Timer(CheckPackages);
            IsExpanded = false;
        }

        private void LoadHintPath(ProjectItem projectItem)
        {
            HintPath = projectItem.Metadata.Any(m => m.Name == "HintPath") ? projectItem.Metadata.Single(m => m.Name == "HintPath").EvaluatedValue : null;

            if (HintPath != null)
            {
                var startIndex = HintPath.IndexOf("\\packages\\", StringComparison.InvariantCulture);
                if (startIndex != -1)
                {
                    startIndex += "\\packages\\".Length;
                    var endIndex = HintPath.IndexOf("\\", startIndex, StringComparison.InvariantCulture);
                    if (endIndex != -1)
                    {
                        IsNuGetReference = true;

                        var isVersionPart = true;
                        var nuGetPackageVersion = string.Empty;
                        var nuGetPackage = string.Empty;

                        var segments = HintPath.Substring(startIndex, endIndex - startIndex).Split('.');
                        foreach (var segment in segments.Reverse())
                        {
                            if (isVersionPart)
                            {
                                int number = 0;
                                if (int.TryParse(segment, out number))
                                {
                                    nuGetPackageVersion = segment + "." + nuGetPackageVersion;
                                }
                                else
                                {
                                    nuGetPackage = segment;
                                    isVersionPart = false;
                                }
                            }
                            else
                                nuGetPackage = segment + "." + nuGetPackage;
                        }

                        NuGetPackageName = nuGetPackage.Trim('.');
                        NuGetPackageVersion = nuGetPackageVersion.Trim('.');
                    }
                }
            }
        }

        public InterpretersNode(
            PythonProjectNode project,
            ProjectItem item,
            IPythonInterpreterFactory factory,
            bool isInterpreterReference,
            bool canDelete,
            bool isGlobalDefault = false
        )
            : base(project, ChooseElement(project, item)) {
            ExcludeNodeFromScc = true;

            _interpreters = project.Interpreters;
            _interpreterService = project.Site.GetComponentModel().GetService<IInterpreterOptionsService>();
            _factory = factory;
            _isReference = isInterpreterReference;
            _canDelete = canDelete;
            _isGlobalDefault = isGlobalDefault;
            _canRemove = !isGlobalDefault;
            _captionSuffix = isGlobalDefault ? SR.GetString(SR.GlobalDefaultSuffix) : "";

            if (Directory.Exists(_factory.Configuration.LibraryPath)) {
                // TODO: Need to handle watching for creation
                try {
                    _fileWatcher = new FileSystemWatcher(_factory.Configuration.LibraryPath);
                } catch (ArgumentException) {
                    // Path was not actually valid, despite Directory.Exists
                    // returning true.
                }
                if (_fileWatcher != null) {
                    try {
                        _fileWatcher.IncludeSubdirectories = true;
                        _fileWatcher.Deleted += PackagesChanged;
                        _fileWatcher.Created += PackagesChanged;
                        _fileWatcher.EnableRaisingEvents = true;
                        // Only create the timer if the file watcher is running.
                        _timer = new Timer(CheckPackages);
                    } catch (IOException) {
                        // Raced with directory deletion
                        _fileWatcher.Dispose();
                        _fileWatcher = null;
                    }
                }
            }
        }

        /// <summary>Initializes a new instance of the <see cref="AssemblyReference"/> class. </summary>
        /// <param name="projectItem">The raw name. </param>
        internal AssemblyReference(ProjectItem projectItem)
        {
            ProjectItem = projectItem;

            var array = ProjectItem.EvaluatedInclude.Split(',');

            _name = array[0];
            _version = "Any";

            foreach (var tuple in array.Skip(1)
                .Select(n => n.Trim().Split('='))
                .Select(n => new Tuple<string, string>(n[0], n[1])))
            {
                switch (tuple.Item1)
                {
                    case "Version":
                        _version = tuple.Item2;
                        break;
                }
            }
        }

        public override void RefreshProperties() {
            ItemProject.BuildProject.ReevaluateIfNecessary();

            _url = base.Url;

            IEnumerable<ProjectItem> items = ItemProject.BuildProject.GetItems(_item.ItemType);
            foreach (ProjectItem projectItem in items) {
                if (projectItem != null && projectItem.UnevaluatedInclude.Equals(_item.UnevaluatedInclude)) {
                    _item = projectItem;
                    return;
                }
            }
        }

        //=====================================================================

        /// <summary>
        /// This constructor is used to wrap an existing reference
        /// </summary>
        /// <param name="project">The project that owns the reference</param>
        /// <param name="existingItem">The existing reference</param>
        /// <overloads>There are two overloads for the constructor</overloads>
        internal ProjectReferenceItem(SandcastleProject project, ProjectItem existingItem) : base(project, existingItem)
        {
            projectPath = new FilePath(this.Include, this.Project);
            projectPath.PersistablePathChanging += projectPath_PersistablePathChanging;
            this.GetProjectMetadata(false);
            this.Include = projectPath.PersistablePath;
        }

        /// <summary>
        /// Helper for SpecialCharactersInMetadataValue tests
        /// </summary>
        internal static void SpecialCharactersInMetadataValueTests(ProjectItem item)
        {
            Assert.Equal("%3B", item.GetMetadata("EscapedSemicolon").UnevaluatedValue);
            Assert.Equal("%3B", item.GetMetadata("EscapedSemicolon").EvaluatedValueEscaped);
            Assert.Equal(";", item.GetMetadata("EscapedSemicolon").EvaluatedValue);
            Assert.Equal("%3B", Project.GetMetadataValueEscaped(item, "EscapedSemicolon"));
            Assert.Equal(";", item.GetMetadataValue("EscapedSemicolon"));

            Assert.Equal("%24", item.GetMetadata("EscapedDollarSign").UnevaluatedValue);
            Assert.Equal("%24", item.GetMetadata("EscapedDollarSign").EvaluatedValueEscaped);
            Assert.Equal("$", item.GetMetadata("EscapedDollarSign").EvaluatedValue);
            Assert.Equal("%24", Project.GetMetadataValueEscaped(item, "EscapedDollarSign"));
            Assert.Equal("$", item.GetMetadataValue("EscapedDollarSign"));
        }

		public MSBuildItemWrapper(MSBuildBasedProject project, MSBuild.ProjectItem item)
		{
			this.project = project;
			this.item = item;
		}

 public FactoryInfo(MSBuild.ProjectItem projectItem, bool owned) {
     ProjectItem = projectItem;
     Owned = owned;
 }

        private bool ResolveProjectReferenceItemByAssemblyName(ProjectItem reference, string mapping)
        {
            if (reference.HasMetadata("HintPath"))
            {
                var hintpath = reference.GetMetadataValue("HintPath");
                var fileInfo = new FileInfo(hintpath);
                return fileInfo.Name.Equals(mapping, StringComparison.OrdinalIgnoreCase);
            }

            return false;
        }

 /// <summary>
 /// Gets the project item with the given full path.
 /// </summary>
 private string GetFullPath(ProjectItem item)
 {
     if (Path.IsPathRooted(item.EvaluatedInclude))
         return item.EvaluatedInclude;
     return Path.Combine(Path.GetDirectoryName(fileName), item.EvaluatedInclude);
 }

        /// <summary>
        /// Constructor to Wrap an existing MSBuild.ProjectItem
        /// Only have internal constructors as the only one who should be creating
        /// such object is the project itself (see Project.CreateFileNode()).
        /// </summary>
        /// <param name="project">Project that owns this item</param>
        /// <param name="existingItem">an MSBuild.ProjectItem; can be null if virtualFolder is true</param>
        /// <param name="virtualFolder">Is this item virtual (such as reference folder)</param>
        internal ProjectElement(ProjectNode project, MSBuild.ProjectItem existingItem, bool virtualFolder)
        {
            if (project == null)
                throw new ArgumentNullException("project");
            if (!virtualFolder && existingItem == null)
                throw new ArgumentNullException("existingItem");

            // Keep a reference to project and item
            this.itemProject = project;
            this.item = existingItem;
            this.isVirtual = virtualFolder;

            if (this.isVirtual)
                this.virtualProperties = new Dictionary<string, string>();
        }

		bool IProjectItemListProvider.RemoveProjectItem(ProjectItem item)
		{
			if (item == null)
				throw new ArgumentNullException("item");
			if (item.Project != this)
				throw new ArgumentException("item does not belong to this project", "item");
			if (!item.IsAddedToProject)
				return false;
			MSBuildItemWrapper backend = (MSBuildItemWrapper)item.BuildItem;
			
			using (var c = OpenCurrentConfiguration()) {
				if (items.Remove(item)) {
					itemsReadOnly = null; // remove readonly variant of item list - will regenerate on next Items call
					c.Project.RemoveItem(backend.MSBuildItem);
					item.BuildItem = null; // make the item free again
					return true;
				} else {
					throw new InvalidOperationException("Expected that the item is added to this project!");
				}
			}
		}