ProjectCollection Class

Definition

Namespace:

Microsoft.Build.Evaluation

Assembly:

Microsoft.Build.dll

Package:

Microsoft.Build v17.11.4

Source:

ProjectCollection.cs

This class encapsulates a set of related projects, their toolsets, a default set of global properties, and the loggers that should be used to build them. A global version of this class acts as the default ProjectCollection. Multiple ProjectCollections can exist within an appdomain. However, these must not build concurrently.

public ref class ProjectCollection : IDisposable

public class ProjectCollection : IDisposable

type ProjectCollection = class
    interface IDisposable

Public Class ProjectCollection
Implements IDisposable

Inheritance

Object

ProjectCollection

Implements

IDisposable

Remarks

Multiple project collections can exist within an app domain. However, these must not build concurrently.

Constructors

ProjectCollection()	Instantiates a project collection with no global properties or loggers that reads toolset information from the configuration file and registry.
ProjectCollection(IDictionary<String,String>, IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>, ToolsetDefinitionLocations, Int32, Boolean, Boolean, Boolean, Boolean)	Instantiates a project collection with specified global properties and loggers and using the specified toolset locations, node count, and setting of onlyLogCriticalEvents. Global properties and loggers may be null. Throws InvalidProjectFileException if any of the global properties are reserved. May throw InvalidToolsetDefinitionException.
ProjectCollection(IDictionary<String,String>, IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>, ToolsetDefinitionLocations, Int32, Boolean, Boolean)	Instantiates a project collection with specified global properties and loggers and using the specified toolset locations, node count, and setting of onlyLogCriticalEvents. Global properties and loggers may be null. Throws InvalidProjectFileException if any of the global properties are reserved. May throw InvalidToolsetDefinitionException.
ProjectCollection(IDictionary<String,String>, IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>, ToolsetDefinitionLocations, Int32, Boolean)	Instantiates a project collection with specified global properties and loggers and using the specified toolset locations, node count, and setting of onlyLogCriticalEvents. Global properties and loggers may be null. Throws InvalidProjectFileException if any of the global properties are reserved. May throw InvalidToolsetDefinitionException.
ProjectCollection(IDictionary<String,String>, IEnumerable<ILogger>, ToolsetDefinitionLocations)	Instantiates a project collection with specified global properties and loggers and using the specified toolset locations. May throw InvalidToolsetDefinitionException.
ProjectCollection(IDictionary<String,String>)	Instantiates a project collection with specified global properties, no loggers, and that reads toolset information from the configuration file and registry. May throw InvalidToolsetDefinitionException.
ProjectCollection(ToolsetDefinitionLocations)	Instantiates a project collection using toolsets from the specified locations, and no global properties or loggers. May throw InvalidToolsetDefinitionException.

Properties

Count	Number of projects currently loaded into this collection.
DefaultToolsVersion	The default tools version of this project collection. Projects use this tools version if they aren't otherwise told what tools version to use. This value is gotten from the .exe.config file, or else in the registry, or if neither specify a default tools version then it is hard-coded to the tools version "2.0". Setter throws InvalidOperationException if a toolset with the provided tools version has not been defined. Always defined.
DisableMarkDirty	Whether MarkDirty() is temporarily disabled on projects in this collection. This allows, for example, global properties to be set without projects getting marked dirty for reevaluation as a consequence.
DisplayVersion	Gets a version of the Engine suitable for display to a user.
GlobalProjectCollection	Retrieves the global project collection object. This is a singleton project collection with no global properties or loggers that reads toolset information from the configuration file and registry. May throw InvalidToolsetDefinitionException. Thread safe.
GlobalProperties	Returns default global properties for all projects in this collection. Read-only dead dictionary.
HostServices	Object exposing host services to tasks during builds of projects contained by this project collection. By default, HostServices is used. May be set to null, but the getter will create a new instance in that case.
IsBuildEnabled	This is the default value used by newly created projects for whether or not the building of projects is enabled. This is for security purposes in case a host wants to closely control which projects it allows to run targets/tasks.
LoadedProjects	All the projects currently loaded into this collection. Each has a unique combination of path, global properties, and tools version.
Loggers	Loggers that all contained projects will use for their builds. Loggers are added with the RegisterLogger(ILogger). Returns an empty collection if there are no loggers.
OnlyLogCriticalEvents	When true, only log critical events such as warnings and errors. Has to be in here for API compat
SkipEvaluation	Whether reevaluation is temporarily disabled on projects in this collection. This is useful when the host expects to make a number of reads and writes to projects, and wants to temporarily sacrifice correctness for performance.
ToolsetLocations	Returns the locations used to find the toolsets.
Toolsets	Returns the toolsets this ProjectCollection knows about.
Version	Gets the file version of the file in which the Engine assembly lies.

Methods

AddToolset(Toolset)	Add a new toolset. Replaces any existing toolset with the same tools version.
ContainsToolset(String)	Returns true if there is a toolset defined for the specified tools version, otherwise false.
Dispose()	Called when a host is completely done with the project collection.
Dispose(Boolean)	Following standard framework guideline dispose pattern. Shut down logging service if the project collection owns one, in order to shut down the logger thread and loggers.
Escape(String)	Escape a string using MSBuild escaping format. For example, "%3b" for ";". Only characters that are especially significant to MSBuild parsing are escaped. Callers can use this method to make a string safe to be parsed to other methods that would otherwise expand it; or to make a string safe to be written to a project file.
GetEffectiveToolsVersion(String, String)	Figure out what ToolsVersion to use to actually build the project with.
GetGlobalProperty(String)	Get any global property on the project collection that has the specified name, otherwise returns null.
GetLoadedProjects(String)	Returns any and all loaded projects with the provided path. There may be more than one, if they are distinguished by global properties and/or tools version.
GetToolset(String)	Get the toolset with the specified tools version. If it is not present, returns null.
LoadProject(String, IDictionary<String,String>, String)	Loads a project with the specified filename, tools version and global properties. If a matching project is already loaded, it will be returned, otherwise a new project will be loaded.
LoadProject(String, String)	Loads a project with the specified filename and tools version, using the collection's global properties. If a matching project is already loaded, it will be returned, otherwise a new project will be loaded.
LoadProject(String)	Loads a project with the specified filename, using the collection's global properties and tools version. If a matching project is already loaded, it will be returned, otherwise a new project will be loaded.
LoadProject(XmlReader, IDictionary<String,String>, String)	Loads a project with the specified reader, tools version and global properties. The project will be added to this project collection when it is named.
LoadProject(XmlReader, String)	Loads a project with the specified reader and tools version, using the collection's global properties. The project will be added to this project collection when it is named.
LoadProject(XmlReader)	Loads a project with the specified reader, using the collection's global properties and tools version. The project will be added to this project collection when it is named.
LogBuildFinishedEvent(Boolean)	Logs a BuildFinished event. This is used specifically when a ProjectCollection is created but never actually built, yet a BuildFinished event is still desired. As an example, if a Project is just meant to be evaluated, but a binlog is also collected, that binlog should be able to say the build succeeded or failed. This provides a mechanism to achieve that.
RegisterForwardingLoggers(IEnumerable<ForwardingLoggerRecord>)	Adds some remote loggers to the collection of remote loggers used for builds of projects in this collection. May be null.
RegisterLogger(ILogger)	Adds a logger to the collection of loggers used for builds of projects in this collection. If the logger object is already in the collection, does nothing.
RegisterLoggers(IEnumerable<ILogger>)	Adds some loggers to the collection of loggers used for builds of projects in this collection. If any logger object is already in the collection, does nothing for that logger. May be null.
RemoveAllToolsets()	Removes all toolsets.
RemoveGlobalProperty(String)	Removes a global property from the collection-level set of global properties, and all projects in the project collection. If it was on this project collection, returns true.
RemoveToolset(String)	Remove a toolset. Returns true if it was present, otherwise false.
SetGlobalProperty(String, String)	Set a global property at the collection-level, and on all projects in the project collection.
TryUnloadProject(ProjectRootElement)	Unloads a project XML root element from the cache entirely, if it is not in use by project loaded into this collection. Returns true if it was unloaded successfully, or was not already loaded. Returns false if it was not unloaded because it was still in use by a loaded Project.
Unescape(String)	Unescape a string using MSBuild escaping format. For example, "%3b" for ";". All escaped characters are unescaped.
UnloadAllProjects()	Unloads all the projects contained by this ProjectCollection. Host should call this when they are completely done with all the projects.
UnloadProject(Project)	Unloads the specific project specified. Host should call this when they are completely done with the project. If project was not already loaded, throws InvalidOperationException.
UnloadProject(ProjectRootElement)	Unloads a project XML root element from the weak cache.
UnregisterAllLoggers()	Removes all loggers from the collection of loggers used for builds of projects in this collection.

Events

ProjectAdded	Event that is fired when a project is added to the ProjectRootElementCache of this project collection.
ProjectChanged	Raised when a Project contained by this instance is directly changed.
ProjectCollectionChanged	Raised when state is changed on this instance.
ProjectXmlChanged	Raised when a ProjectRootElement contained by this instance is changed.