Add guidance for .NET library dependency versions

[ericstj]

This is first draft. I might be assuming too much familiarity with the problem space. Please provide feedback 🤝

---

Internal previews

📄 File	🔗 Preview link
docs/standard/library-guidance/dependencies-net.md	docs/standard/library-guidance/dependencies-net

[Copilot]

Pull Request Overview

This PR introduces comprehensive guidance for .NET library authors on selecting dependency versions when targeting multiple .NET framework versions. The document outlines three primary strategies (latest supported versions, TFM-specific versions, and branching), their tradeoffs, and provides concrete recommendations with code examples.

Key changes:

• New guidance document explaining dependency version selection strategies for .NET libraries.
• Decision matrix comparing engineering, servicing, and update friction costs across strategies.
• Code examples demonstrating each approach using System.Text.Json references.

[ericstj]

I've addressed all feedback, please have another pass at this. Thank you.

[gewarren]

You'll need to add this to the TOC somewhere. Maybe below this article in this file?

[gewarren]

Suggested change

	ai-usage: ai-assisted
	title: Guidance for .NET library dependency versions
	description: Learn about the strategies and recommendations for choosing dependency versions when you build a library that targets multiple .NET versions.
	ms.date: 11/24/2025
	ai-usage: ai-assisted

[gewarren]

Suggested change

	When building libraries that target multiple .NET versions, choosing dependency versions has implications for compatibility, servicing, and ecosystem health. This document outlines the main strategies, their tradeoffs, and recommendations.
	---
	When you build libraries that target multiple .NET versions, choosing dependency versions has implications for compatibility, servicing, and ecosystem health. This article outlines the main strategies, their tradeoffs, and recommendations.

[gewarren]

Suggested change

	## **Overview**
	## Overview

[gewarren]

Suggested change

	Library authors face challenges when deciding which version of a .NET dependency to reference. Newer versions have more API and features, but may require a local redistribution increasing servicing responsibilities of the library and size of the application. The decision impacts:
	Library authors face challenges when deciding which version of a .NET dependency to reference. Newer versions have more APIs and features but might require a local redistribution, which increases servicing responsibilities of the library and size of the application. The decision impacts:

[gewarren]

Suggested change

	```xml
	```xml

[gewarren]

Suggested change

	```xml
	```xml

[gewarren]

Suggested change

	Branch: release/8.0
	Branch: release/8.0

[gewarren]

Suggested change

	Branch: release/9.0
	Branch: release/9.0

[gewarren]

Suggested change

	Branch: release/10.0
	Branch: release/10.0

[eerhardt]

Sorry I wasn't clear earlier about the example.

I think a good example here would be Microsoft.Extensions.Logging.Abstractions. It isn't in the shared framework, but lifts a dependency on a library that is in the shared framework.

https://www.nuget.org/packages/Microsoft.Extensions.Logging.Abstractions/#dependencies-body-tab

If a library references the 10.0.0 version of Microsoft.Extensions.Logging.Abstractions, System.Diagnostics.DiagnosticSource will be lifted out of the shared framework for all net8 and net9 apps that reference the library.