Document binding redirect generation for unit test projects (DLL targets)

[Copilot]

Unit test projects compile to DLLs and are silently excluded from automatic binding redirect generation, causing runtime FileLoadException when assembly version conflicts exist—with no documentation explaining why or how to fix it.

Changes

• redirect-assembly-versions.md: Added a new subsection under "Redirect versions for tests, plugins, or libraries used by another component" explaining:
  • Why DLL output types are excluded from automatic binding redirect generation
  • How to force .dll.config generation via two MSBuild properties
  • That VSTest and most test runners automatically load the generated config file

<PropertyGroup>
  <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
  <GenerateBindingRedirectsOutputType>true</GenerateBindingRedirectsOutputType>
</PropertyGroup>

After rebuilding, a .dll.config file appears alongside the test assembly in the output directory containing the generated binding redirects.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[New Topic] Improve documentation on Assembly Binding Redirection </issue_title>
<issue_description>Currently, assembly binding redirection documentation is messy and difficult to locate. This is especially true if you're not able to use automatic binding redirection, such as if you are:

• Writing unit tests (which compile to DLLs, and don't get automatic binding redirects)
• Writing DLLs that are consumed in dynamic languages (Powershell, Python)

Most of the documentation is spread across multiple documentation pages, and the bulk of it is not written for .NET Core. Unfortunately, it's incredibly easy to end up with binding redirect problems if you're consuming .NET Standard DLLs from a project that targets either .NET Framework or dual-targets Framework and Core.

This can be improved by:

• Documenting where to include redirect generation options in a .NET Core csproj file (and what the options do)
• Improving documentation on how to force generation of a .config redirect file, even on DLL targets (see Binding Redirects necessary to run Unit Tests on .NET Framework are not preserved when running in testhost microsoft/vstest#428 (comment)). This is necessary to get unit tests to work.
• Documenting that automatic binding redirection fails when compiling DLLs that will be consumed by dynamic languages. This is currently not documented.
• Including examples on how to programmatically add binding redirects to work around the issue. There's an excellent example here that can likely be used, which just a few extra lines to show how to attach the event handler. (https://github.com/Microsoft/dotnet-apiport/blob/dev/src/ApiPort.VisualStudio/AssemblyRedirectResolver.cs)
  </issue_description>

<agent_instructions>Limit the fix to providing information necessary for unit testing scenarios.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@mairaw Thanks @SZ-MSFT for your feedback. @richlander @terrajobst who would know about this and what we want to expose in the docs? @ The existing documentation doesn't explain DLL targets do not get redirection, so they need to be handled manually - this is important if you're writing DLLs that are consumed by dynamic languages, or if you're writing unit tests.

Specifically, it would be great to see documentation on how to get unit tests working (which require special flags in the csproj to allow for redirection to work on a unit test target) - the GenerateBindingRedirectsOutputType flag:
microsoft/vstest#428 (comment)

It would also be great to see an example on how to do binding redirection in code, like in the example I linked to in the original post. If you're someone who is consuming DLLs via dynamic languages, that's the only way to ensure binding redirection works correctly.

@dotnet-bot This issue has been closed as part of the issue backlog grooming process outlined in #22351.

That automated process may have closed some issues that should be addressed. If you think this is one of them, reopen it with a comment explaining why. Tag the @dotnet/docs team for visibility.</comment_new>
<comment_new>@BillWagner
reopening per comment.</comment_new>

• Fixes [New Topic] Improve documentation on Assembly Binding Redirection  #3683

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

---

Internal previews

📄 File	🔗 Preview link
docs/framework/configure-apps/redirect-assembly-versions.md	Redirect assembly versions

[BillWagner]

This is ready for final review.

[Copilot]

Pull request overview

Updates the .NET Framework assembly binding redirect documentation to explain why unit test projects (DLL outputs) don’t get automatic binding redirect generation and how to enable .dll.config generation via MSBuild properties.

Changes:

• Expanded article metadata to reflect added unit test guidance.
• Added a new subsection describing how to generate binding redirects for unit test projects by setting AutoGenerateBindingRedirects and GenerateBindingRedirectsOutputType.