Clarify DeploymentItemAttribute XML doc comments - #8968
Merged
Amaury Levé (Evangelink) merged 2 commits intoJun 10, 2026
Merged
Conversation
Replace the unclear reference to RunConfig.RelativePathRoot with a description of the build output directory, mention legacy-mode behavior, and replace the confusing [DeploymentItem(`"bin\Debug`")] sample with three clearer examples wrapped in a <code> block. Fixes microsoft#8960.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the XML documentation on DeploymentItemAttribute (MSTest TestFramework.Extensions) to remove legacy/unclear terminology and provide clearer guidance and examples for how deployment item paths are resolved.
Changes:
- Reworded the
<summary>to describe deployment behavior in terms ofTestContext.DeploymentDirectoryand the build output directory. - Added a legacy-mode note in
<remarks>about alternate relative path resolution roots. - Improved the
<example>formatting and replaced the previous snippet with clearer real-world examples.
Show a summary per file
| File | Description |
|---|---|
| src/TestFramework/TestFramework.Extensions/Attributes/DeploymentItemAttribute.cs | Clarifies DeploymentItemAttribute XML docs (summary/remarks/examples) and modernizes the guidance around relative path roots. |
Copilot's findings
- Files reviewed: 1/1 changed files
- Comments generated: 2
Amaury Levé (Evangelink)
enabled auto-merge (squash)
June 9, 2026 14:26
- Remove the <para> mentioning RunSettings/MSTest/ForcedLegacyMode. The setting isn't recognized anywhere in this codebase (MSTest v3 ignores .testsettings and <LegacySettings> outright), so the note risked pointing readers at a non-existent knob. - Switch the example path separators from Windows-style backslashes (which forced verbatim strings) to forward slashes so the snippet works as-is on Windows, Linux, and macOS test runs.
Jan Krivanek (JanKrivanek)
approved these changes
Jun 9, 2026
Amaury Levé (Evangelink)
added a commit
to dotnet/docs
that referenced
this pull request
Jun 22, 2026
* Add MSTest DeploymentItem sub-page Adds a new `Write tests` sub-page that documents `DeploymentItemAttribute` end to end: how it resolves relative paths against the build output directory, the two constructor overloads, how to stage source files via `CopyToOutputDirectory` or post-build events, `TestContext.DeploymentDirectory`, `DeploymentEnabled`, legacy mode caveats, and best practices. Cross-links the new page from the main Write tests page (description table + attribute quick reference) and the TestContext page, and wires the entry into devops-testing/toc.yml. Related to microsoft/testfx#8960 (the matching XML doc comment fix on the attribute is microsoft/testfx#8968). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix DeploymentItem snippet compile issues and rename heading - Add missing 'using System.IO;' to the two snippets that use File/Path. - Drop trailing backslash from verbatim folder paths (@"TestFiles\" and @"Resources\") since C# verbatim string literals can't end with a single backslash. - Rename 'Use a post-build event' section to 'Use a post-build target' to match the MSBuild <Target> example. Addresses review comments on PR #54210. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #8960.
Summary
The XML doc comments on
DeploymentItemAttributereferencedRunConfig.RelativePathRoot, a legacy term that's unclear to modern MSTest users. The example block also included a confusing[DeploymentItem(""bin\Debug"")]line that doesn't reflect realistic usage.Changes
<summary>: Replaced theRunConfig.RelativePathRootreference with a clear statement that relative paths resolve against the build output directory (the folder that contains the test assembly). Tightened the wording aroundTestContext.DeploymentDirectory.<remarks>: Added a<para>note that, in legacy mode (.testsettingsorRunSettings/MSTest/ForcedLegacyMode), relative paths might be resolved against the solution root instead.<example>: Wrapped the snippet in<code>(so it renders as code in IDEs / docs.microsoft.com). Removed the confusing[DeploymentItem(""bin\Debug"")]line and replaced the block with three clear, real-world examples (single file, file with subfolder, folder with trailing separator), each annotated with what it does.Constructor-level
<param>docs already correctly state that the path is relative to the build output directory; left unchanged.A separate PR will update dotnet/docs to add a dedicated DeploymentItem section under the MSTest "Write tests" sub-pages.