Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
28cdd17
Add Directory.Parse.config to skip unknown attributes/elements during…
benwitmanmsft Jul 30, 2026
7dee374
Switch Directory.Parse.config to XML format
benwitmanmsft Jul 31, 2026
7a06433
Fix config lifecycle: startup-dir loading, server isolation, worker n…
benwitmanmsft Aug 3, 2026
af672ec
Make UnknownElementsConfiguration config parameter explicit on all va…
benwitmanmsft Aug 3, 2026
1d70e71
Simplify config sources: env var + project directory walk only
benwitmanmsft Aug 3, 2026
f163eba
Embed Directory.Parse.config files in binlog via ProjectImportedEvent…
benwitmanmsft Aug 3, 2026
4c55cde
Update src/Build/Construction/ProjectRootElement.cs
JanProvaznik Aug 4, 2026
ae86faa
Wire ImportGroup child validation through UnknownElementsConfiguration
benwitmanmsft Aug 4, 2026
93625a3
Update spec documentation to reflect current implementation
benwitmanmsft Aug 4, 2026
4f795cb
Embed config files in binlog via projectImportsCollector instead of f…
benwitmanmsft Aug 4, 2026
e688262
Clarify Item attributes
benwitmanmsft Aug 4, 2026
ce7cf93
Add comprehensive data-driven tests for all documented elements
benwitmanmsft Aug 4, 2026
1909481
Rename UnknownElementsConfiguration to ParserIgnoreConfiguration
benwitmanmsft Aug 10, 2026
530f536
Replace hardcoded generic element name strings with constants
benwitmanmsft Aug 11, 2026
2ace693
Replace Load/UnloadParseConfigForStartup with constructor parameter
benwitmanmsft Aug 11, 2026
5891abc
Fix NotImplementedException when applying parse config to a new cache
JanProvaznik Aug 11, 2026
9c4b962
Enable nullable in ParserIgnoreConfiguration_Tests.cs
benwitmanmsft Aug 11, 2026
f1f75a9
Default _ParserIgnoreConfiguration to Empty in BuildParameters
benwitmanmsft Aug 11, 2026
0651131
Fix unbounded growth of binlog embed paths and skipped items
benwitmanmsft Aug 11, 2026
7210435
Update spec and class docs to match current implementation
benwitmanmsft Aug 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions documentation/specs/directory-parse-config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Directory.Parse.config — Ignoring Unexpected Attributes and Elements

## Summary

MSBuild now supports a configuration file (`Directory.Parse.config`) that allows specific unrecognized attributes or child elements to be silently skipped during project parsing, instead of throwing `InvalidProjectFileException` (MSB4066/MSB4067).

This enables compatibility scenarios where project files may include attributes/elements intended for newer MSBuild versions or third-party tools that can still build without those attributes/elements.

## Configuration File Format

`Directory.Parse.config` is an XML file:

```xml
<ParseConfig>
<IgnoreAttributes>
<Ignore Element="Target" Name="CustomAttr" />
<Ignore Element="Property" Name="NewFeatureFlag" />
</IgnoreAttributes>
<IgnoreChildren>
<Ignore Element="Project" Name="CustomElement" />
<Ignore Element="Task" Name="CustomChild" />
</IgnoreChildren>
</ParseConfig>
```

- **Root element**: `<ParseConfig>`
- **`<IgnoreAttributes>`**: Contains `<Ignore>` entries for attributes to skip. Appears 0 or 1 times.
- **`<IgnoreChildren>`**: Contains `<Ignore>` entries for child elements to skip. Appears 0 or 1 times.
- **`<Ignore>`**: Each entry has `Element` (the parent/owner element name) and `Name` (the attribute or child to allow).

Matching is case-insensitive. Entries with missing or empty `Element`/`Name` attributes are silently ignored. Unrecognized sections or elements are ignored.

### Valid `IgnoreAttributes` Elements

The `Element` attribute in `<IgnoreAttributes>` entries can be:
- `Target`
- `PropertyGroup`
- `ItemGroup`
- `Import`
- `ImportGroup`
- `UsingTask`
- `OnError`
- `Output`
- `Choose`
- `Otherwise`
- `ProjectExtensions`

Generic names for dynamically-named elements:

| Generic Name | Applies To |
|---|---|
| `Property` | Any property element (child of `PropertyGroup`) |
| `Item` | Any item element (child of `ItemGroup`) |
| `ItemDefinition` | Any item definition element (child of `ItemDefinitionGroup`) |
| `Metadata` | Any metadata element (child of an `Item` or `ItemDefinition`) |
| `Parameter` | Any parameter element in a `ParameterGroup` inside `UsingTask` |
| `UsingTaskBody` | The `Task` element inside `UsingTask` |

Note: `Item` only applies to attributes with leading underscores as any other attributes are interpreted as metadata names.

### Valid `IgnoreChildren` Elements

The `Element` attribute in `<IgnoreChildren>` entries can be:
- `Project`
- `Import`
- `ImportGroup`
- `Task`
- `UsingTask`
- `OnError`
- `Output`
- `Choose`
- `When`
- `Otherwise`

Not applicable (children are free-form by design):

- `Target`
- `PropertyGroup`
- `ItemGroup`
- `ItemDefinitionGroup`
- `ProjectExtensions`

## Discovery and Loading

Configuration is discovered from two sources:

1. **`MSBUILD_PARSE_CONFIG` environment variable** — Semicolon-separated (Windows) or colon-separated (Unix) list of config file paths. Always loaded when a `ProjectCollection` is created.

2. **Project directory walk** — The CLI walks up from the target project file's directory looking for `Directory.Parse.config` (same pattern as `Directory.Build.rsp`). This is passed as `parseConfigDirectory` to the `ProjectCollection` constructor.

These are merged additively — entries from either source are combined.

## Integration

The `ProjectCollection` constructor accepts an optional `parseConfigDirectory` parameter. When provided, it walks up from that directory to find a `Directory.Parse.config` and merges it with the environment variable config. XMake passes the project file's directory.

The `ParserIgnoreConfiguration` property on `ProjectCollection` and `BuildParameters` is `internal`. External hosts that need to configure parse rules should use the constructor parameter or the environment variable.

## Logging

- **Config files loaded**: Logged at evaluation start (`MessageImportance.Low`). Lists all loaded config file paths.
- **Config files embedded**: Each loaded config file is embedded in the binary log archive (visible as an embedded file, not as a project import).
- **Skipped items summary**: Logged after each evaluation completes (`MessageImportance.Low`). Lists skipped attributes/elements with occurrence counts for that evaluation.

## Feature Flag

Set `MSBUILD_DISABLE_PARSE_CONFIG=1` to disable all automatic config loading.

## Examples

### Allow a custom attribute on all Target elements

```xml
<ParseConfig>
<IgnoreAttributes>
<Ignore Element="Target" Name="CustomAttr" />
</IgnoreAttributes>
</ParseConfig>
```

Allows `<Target Name="Build" CustomAttr="value">` without error.

### Allow a custom child element under Project

```xml
<ParseConfig>
<IgnoreChildren>
<Ignore Element="Project" Name="ToolConfiguration" />
</IgnoreChildren>
</ParseConfig>
```

Allows `<ToolConfiguration ... />` as a direct child of `<Project>` without error.
Loading
Loading