diff --git a/documentation/specs/directory-parse-config.md b/documentation/specs/directory-parse-config.md
new file mode 100644
index 00000000000..900620c9459
--- /dev/null
+++ b/documentation/specs/directory-parse-config.md
@@ -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
+
+
+
+
+
+
+
+
+
+
+```
+
+- **Root element**: ``
+- **``**: Contains `` entries for attributes to skip. Appears 0 or 1 times.
+- **``**: Contains `` entries for child elements to skip. Appears 0 or 1 times.
+- **``**: 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 `` 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 `` 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
+
+
+
+
+
+```
+
+Allows `` without error.
+
+### Allow a custom child element under Project
+
+```xml
+
+
+
+
+
+```
+
+Allows `` as a direct child of `` without error.
diff --git a/src/Build.UnitTests/Evaluation/ParserIgnoreConfiguration_Tests.cs b/src/Build.UnitTests/Evaluation/ParserIgnoreConfiguration_Tests.cs
new file mode 100644
index 00000000000..af001490354
--- /dev/null
+++ b/src/Build.UnitTests/Evaluation/ParserIgnoreConfiguration_Tests.cs
@@ -0,0 +1,284 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Microsoft.Build.Exceptions;
+using Microsoft.Build.Evaluation;
+using Shouldly;
+using Xunit;
+
+
+namespace Microsoft.Build.UnitTests.Evaluation
+{
+ public class ParserIgnoreConfiguration_Tests : IDisposable
+ {
+ private readonly string _testDir;
+
+ public ParserIgnoreConfiguration_Tests()
+ {
+ _testDir = Path.Combine(Path.GetTempPath(), "MSBuildTest_UnknownElements_" + Guid.NewGuid().ToString("N"));
+ Directory.CreateDirectory(_testDir);
+ }
+
+ public void Dispose()
+ {
+ if (Directory.Exists(_testDir))
+ {
+ Directory.Delete(_testDir, recursive: true);
+ }
+ }
+
+ [Fact]
+ public void ParsesValidConfigFile()
+ {
+ string configPath = Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName);
+ File.WriteAllText(configPath, @"
+
+
+
+
+
+
+
+");
+
+ var config = ParserIgnoreConfiguration.LoadFromFile(configPath);
+
+ config.LoadedConfigFiles.Count.ShouldBe(1);
+ config.CheckSkipAttribute("Target", "Foo").ShouldBeTrue();
+ config.CheckSkipElement("Project", "CustomThing").ShouldBeTrue();
+ config.CheckSkipAttribute("PropertyGroup", "Bar").ShouldBeTrue();
+ }
+
+ [Fact]
+ public void IsCaseInsensitive()
+ {
+ string configPath = Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName);
+ File.WriteAllText(configPath, @"");
+
+ var config = ParserIgnoreConfiguration.LoadFromFile(configPath);
+
+ config.CheckSkipAttribute("target", "foo").ShouldBeTrue();
+ config.CheckSkipAttribute("TARGET", "FOO").ShouldBeTrue();
+ config.CheckSkipAttribute("Target", "Foo").ShouldBeTrue();
+ }
+
+ [Fact]
+ public void IgnoresInvalidEntries()
+ {
+ string configPath = Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName);
+ File.WriteAllText(configPath, @"
+
+
+
+
+
+
+
+
+
+
+
+");
+
+ var config = ParserIgnoreConfiguration.LoadFromFile(configPath);
+
+ config.CheckSkipAttribute("Target", "ValidOne").ShouldBeTrue();
+ config.CheckSkipAttribute("Target", "Foo").ShouldBeFalse();
+ config.CheckSkipAttribute("Target", "Bar").ShouldBeFalse();
+ config.CheckSkipAttribute("Target", "Nope").ShouldBeFalse();
+ config.CheckSkipAttribute("Target", "Nope2").ShouldBeFalse();
+ }
+
+ [Fact]
+ public void ReturnsEmptyWhenNoConfigExists()
+ {
+ var config = ParserIgnoreConfiguration.LoadFromFile(Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName));
+
+ config.LoadedConfigFiles.Count.ShouldBe(0);
+ config.CheckSkipAttribute("Target", "Foo").ShouldBeFalse();
+ }
+
+ [Fact]
+ public void MergeCombinesEntriesAndDeduplicatesFiles()
+ {
+ string configPath = Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName);
+ File.WriteAllText(configPath, @"");
+
+ string extraConfigPath = Path.Combine(_testDir, "extra.config");
+ File.WriteAllText(extraConfigPath, @"");
+
+ var merged = ParserIgnoreConfiguration.Merge(
+ ParserIgnoreConfiguration.LoadFromFile(configPath),
+ ParserIgnoreConfiguration.LoadFromFile(extraConfigPath));
+ merged = ParserIgnoreConfiguration.Merge(merged, ParserIgnoreConfiguration.LoadFromFile(configPath));
+
+ merged.CheckSkipAttribute("Target", "Foo").ShouldBeTrue();
+ merged.CheckSkipElement("Project", "CustomThing").ShouldBeTrue();
+ merged.LoadedConfigFiles.Count.ShouldBe(2);
+ }
+
+ [Fact]
+ public void LoadGlobalConfigLoadsEnvironmentVariablePaths()
+ {
+ string envConfigPath = Path.Combine(_testDir, "env.config");
+ File.WriteAllText(envConfigPath, @"");
+
+ string? oldEnv = Environment.GetEnvironmentVariable(ParserIgnoreConfiguration.EnvironmentVariableName);
+ try
+ {
+ Environment.SetEnvironmentVariable(ParserIgnoreConfiguration.EnvironmentVariableName, envConfigPath);
+ var config = ParserIgnoreConfiguration.LoadGlobalConfig();
+
+ config.CheckSkipElement("Project", "CustomThing").ShouldBeTrue();
+ }
+ finally
+ {
+ Environment.SetEnvironmentVariable(ParserIgnoreConfiguration.EnvironmentVariableName, oldEnv);
+ }
+ }
+
+ [Fact]
+ public void ConfigurationIsAppliedToSimpleProjectRootElementCache()
+ {
+ string envConfigPath = Path.Combine(_testDir, "env.config");
+ File.WriteAllText(envConfigPath, @"");
+
+ using TestEnvironment env = TestEnvironment.Create();
+ env.SetEnvironmentVariable("MsBuildUseSimpleProjectRootElementCacheConcurrency", "true");
+ env.SetEnvironmentVariable(ParserIgnoreConfiguration.EnvironmentVariableName, envConfigPath);
+
+ using var projectCollection = new ProjectCollection();
+
+ projectCollection.ProjectRootElementCache.ShouldBeOfType();
+ projectCollection.ParserIgnoreConfiguration.CheckSkipElement("Project", "CustomThing").ShouldBeTrue();
+
+ // Replacing the configuration invalidates what the cache parsed under the old one, which the simple
+ // cache has to be able to do as well.
+ projectCollection.ParserIgnoreConfiguration = ParserIgnoreConfiguration.Empty;
+ projectCollection.ParserIgnoreConfiguration.CheckSkipElement("Project", "CustomThing").ShouldBeFalse();
+ }
+
+ [Fact]
+ public void RecordsSkippedItems()
+ {
+ string configPath = Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName);
+ File.WriteAllText(configPath, @"");
+
+ var config = ParserIgnoreConfiguration.LoadFromFile(configPath);
+
+ config.GetSkippedSummaryMessage().ShouldBeNull();
+
+ config.CheckSkipAttribute("Target", "Foo");
+ config.CheckSkipAttribute("Target", "Foo");
+
+ string? summary = config.GetSkippedSummaryMessage();
+ summary.ShouldNotBeNull();
+ summary.ShouldContain("Attribute:Target:Foo");
+ summary.ShouldContain("2 occurrences");
+ }
+
+ [Theory]
+ [MemberData(nameof(AttributeSkipCases))]
+ public void AllowedAttributeIsSkipped(string configElement, string configName, string projectXml)
+ {
+ string configPath = Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName);
+ File.WriteAllText(configPath, $@"");
+ string projectFile = Path.Combine(_testDir, "test.proj");
+ File.WriteAllText(projectFile, projectXml);
+
+ using (var pc = CreateProjectCollection(ParserIgnoreConfiguration.LoadFromFile(configPath)))
+ {
+ var project = new Project(projectFile, null, null, pc, ProjectLoadSettings.IgnoreMissingImports | ProjectLoadSettings.IgnoreEmptyImports | ProjectLoadSettings.IgnoreInvalidImports);
+ project.ShouldNotBeNull();
+ }
+ }
+
+ [Theory]
+ [MemberData(nameof(AttributeSkipCases))]
+ public void NonAllowedAttributeThrows(string configElement, string configName, string projectXml)
+ {
+ _ = configElement;
+ _ = configName;
+ string projectFile = Path.Combine(_testDir, "test.proj");
+ File.WriteAllText(projectFile, projectXml);
+
+ using (var pc = CreateProjectCollection(ParserIgnoreConfiguration.Empty))
+ {
+ Should.Throw(() => new Project(projectFile, null, null, pc, ProjectLoadSettings.IgnoreMissingImports | ProjectLoadSettings.IgnoreEmptyImports | ProjectLoadSettings.IgnoreInvalidImports));
+ }
+ }
+
+ [Theory]
+ [MemberData(nameof(ChildSkipCases))]
+ public void AllowedChildIsSkipped(string configElement, string configName, string projectXml)
+ {
+ string configPath = Path.Combine(_testDir, ParserIgnoreConfiguration.ConfigFileName);
+ File.WriteAllText(configPath, $@"");
+ string projectFile = Path.Combine(_testDir, "test.proj");
+ File.WriteAllText(projectFile, projectXml);
+
+ using (var pc = CreateProjectCollection(ParserIgnoreConfiguration.LoadFromFile(configPath)))
+ {
+ var project = new Project(projectFile, null, null, pc, ProjectLoadSettings.IgnoreMissingImports | ProjectLoadSettings.IgnoreEmptyImports | ProjectLoadSettings.IgnoreInvalidImports);
+ project.ShouldNotBeNull();
+ }
+ }
+
+ [Theory]
+ [MemberData(nameof(ChildSkipCases))]
+ public void NonAllowedChildThrows(string configElement, string configName, string projectXml)
+ {
+ _ = configElement;
+ _ = configName;
+ string projectFile = Path.Combine(_testDir, "test.proj");
+ File.WriteAllText(projectFile, projectXml);
+
+ using (var pc = CreateProjectCollection(ParserIgnoreConfiguration.Empty))
+ {
+ Should.Throw(() => new Project(projectFile, null, null, pc, ProjectLoadSettings.IgnoreMissingImports | ProjectLoadSettings.IgnoreEmptyImports | ProjectLoadSettings.IgnoreInvalidImports));
+ }
+ }
+
+ public static IEnumerable