PublishDepsFilePath breaking change

docs/core/compatibility/3.1-5.0.md

@@ -317,8 +317,13 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 
 ## MSBuild
 
+- [PublishDepsFilePath behavior change](#publishdepsfilepath-behavior-change)
 - [Directory.Packages.props files is imported by default](#directorypackagesprops-files-is-imported-by-default)
 
+[!INCLUDE [publishdepsfilepath-behavior-change](../../../includes/core-changes/msbuild/5.0/publishdepsfilepath-behavior-change.md)]
+
+***
+
 [!INCLUDE [directory-packages-props-imported-by-default](../../../includes/core-changes/msbuild/5.0/directory-packages-props-imported-by-default.md)]
 
 ***

docs/core/compatibility/msbuild.md

@@ -7,11 +7,18 @@ ms.date: 02/10/2020
 
 The following breaking changes are documented on this page:
 
-- [Directory.Packages.props files is imported by default](#directorypackagesprops-files-is-imported-by-default)
-- [Resource manifest file name change](#resource-manifest-file-name-change)
+| Breaking change | Version introduced |
+| - | - |
+| [PublishDepsFilePath behavior change](#publishdepsfilepath-behavior-change) | 5.0 |
+| [Directory.Packages.props files is imported by default](#directorypackagesprops-files-is-imported-by-default) | 5.0 |
+| [Resource manifest file name change](#resource-manifest-file-name-change) | 3.0 |
 
 ## .NET 5.0
 
+[!INCLUDE [publishdepsfilepath-behavior-change](../../../includes/core-changes/msbuild/5.0/publishdepsfilepath-behavior-change.md)]
+
+***
+
 [!INCLUDE [directory-packages-props-imported-by-default](../../../includes/core-changes/msbuild/5.0/directory-packages-props-imported-by-default.md)]
 
 ***

includes/core-changes/msbuild/5.0/publishdepsfilepath-behavior-change.md

@@ -0,0 +1,41 @@
+### PublishDepsFilePath behavior change
+
+The `PublishDepsFilePath` MSBuild property is empty for single-file applications. Additionally, for non single-file applications, the *deps.json* file may not be copied to the output directory until later in the build.
+
+#### Version introduced
+
+5.0
+
+#### Change description
+
+In previous .NET versions, the `PublishDepsFilePath` MSBuild property is the path to the app's *deps.json* file in the output directory for non single-file applications, and a path in the intermediate directory for single-file apps.
+
+Starting in .NET 5.0, `PublishDepsFilePath` is empty for single-file applications and a new `IntermediateDepsFilePath` property specifies the *deps.json* location in the intermediate directory. Additionally, for non single-file applications, the *deps.json* file may not be copied to the output directory (that is, the path specified by `PublishDepsFilePath`) until later in the build.
+
+#### Reason for change
+
+This change was made for a couple of reasons:
+
+- Due to a refactoring of the publish logic in order to support [improved single-file apps](https://github.com/dotnet/designs/blob/master/accepted/2020/single-file/design.md) in .NET 5.
+
+- In single-file apps, to help guard against targets that try to rewrite the *deps.json* file after *deps.json* has already been bundled, thus silently not affecting the app. For this reason, `PublishDepsFilePath` is empty for single-file applications.
+
+#### Recommended action
+
+Targets that rewrite the *deps.json* file should generally do so using the `IntermediateDepsFilePath` property.
+
+#### Category
+
+MSBuild
+
+#### Affected APIs
+
+N/A
+
+<!--
+
+#### Affected APIs
+
+Not detectable via API analysis.
+
+-->