[.NET Guidelines] Target frameworks + dependencies #8550

jsquire · 2025-02-18T18:16:36Z

Summary

The focus of these changes is to update information around the strategy for managing .NET target frameworks for Azure SDK packages and versions for .NET runtime dependencies. Also included are some light refactoring of structure for improved organization and some typo fixes for better readability.

docs/dotnet/introduction.md

christothes · 2025-02-19T16:17:36Z

docs/dotnet/introduction.md

+
+{% include requirement/MUST id="dotnet-dependency-supported-versions" %} ensure all dependencies reference version supported by the publisher that is not marked as deprecated or flagged by NuGet for vulnerabilities. 
+
+{% include requirement/MUST id="dotnet-dependency-compatibile-versions" %} consider all platforms that your library will run on and ensure dependencies/versions are compatible. For example, the Azure Functions host and Azure PowerShell have explicit version requirements for dependencies shared between the host and applications.  


should we link to more information here or maybe even the Packages.Data.props file here?

Maybe? I added it, let's see how it works out.

scottaddie · 2025-02-20T19:49:33Z

docs/dotnet/introduction.md

@@ -667,11 +667,11 @@ public class CopyFromUriOperation {

 ##### Conditional Request Methods

-Some services support conditional requests that are used to implement optimistic concurrency control. In Azure, optimistic concurency is typically implemented using If-Match headers and ETags. See [Managing Concurrency in Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/concurrency-manage?tabs=dotnet) as a good example.
+Some services support conditional requests that are used to implement optimistic concurrency control. In Azure, optimistic concurency is typically implemented using If-Match headers and ETags. See [Managing Concurrency in Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/concurrency-manage?tabs=dotnet) as a good example.


Omit the "en-us" locale strings all throughout

Suggested change

Some services support conditional requests that are used to implement optimistic concurrency control. In Azure, optimistic concurency is typically implemented using If-Match headers and ETags. See [Managing Concurrency in Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/concurrency-manage?tabs=dotnet) as a good example.

Some services support conditional requests that are used to implement optimistic concurrency control. In Azure, optimistic concurrency is typically implemented using `If-Match` headers and ETags. See [Managing Concurrency in Blob Storage](https://learn.microsoft.com/azure/storage/blobs/concurrency-manage?tabs=dotnet) as a good example.

scottaddie · 2025-02-20T20:56:14Z

docs/dotnet/introduction.md

@@ -1029,32 +1029,14 @@ public static class ConfigurationModelFactory {

 {% include requirement/MUST id="dotnet-packaging-nuget" %} package all components as NuGet packages.

-If your client library is built by the Azure SDK engineering systems, all packaging requirements will be met automatically. Follow the [.NET packaging guidelines](https://docs.microsoft.com/dotnet/standard/library-guidance/nuget) if you're self-publishing. For Microsoft owned packages we need to support both windows (for windows dump diagnostics) and portable (for x-platform debugging) pdb formats which means you need to publish them to the Microsoft symbol server and not the Nuget symbol server which only supports portable pdbs.
+If your client library is built by the Azure SDK engineering systems, all packaging requirements will be met automatically. Follow the [.NET packaging guidelines](https://learn.microsoft.com/dotnet/standard/library-guidance/nuget) if you're self-publishing. For Microsoft owned packages, we need to support both windows (for windows dump diagnostics) and portable (for x-platform debugging) pdb formats which means you need to publish them to the Microsoft symbol server and not the NuGet symbol server which only supports portable pdbs.


Suggested change

If your client library is built by the Azure SDK engineering systems, all packaging requirements will be met automatically. Follow the [.NET packaging guidelines](https://learn.microsoft.com/dotnet/standard/library-guidance/nuget) if you're self-publishing. For Microsoft owned packages, we need to support both windows (for windows dump diagnostics) and portable (for x-platform debugging) pdb formats which means you need to publish them to the Microsoft symbol server and not the NuGet symbol server which only supports portable pdbs.

If your client library is built by the Azure SDK engineering systems, all packaging requirements will be met automatically. Follow the [.NET packaging guidelines](https://learn.microsoft.com/dotnet/standard/library-guidance/nuget) if you're self-publishing. For Microsoft-owned packages, we need to support both Windows (for Windows dump diagnostics) and portable (for cross-platform debugging) pdb formats. This means you need to publish them to the Microsoft symbol server and not the NuGet symbol server which only supports portable pdbs.

scottaddie · 2025-02-20T20:57:19Z

docs/dotnet/introduction.md


 Consistent version number scheme allows consumers to determine what to expect from a new version of the library.

-{% include requirement/MUST id="dotnet-version-semver" %} use _MAJOR_._MINOR_._PATCH_ format for the version of the library dll and the NuGet package.
+{% include requirement/MUST id="dotnet-version-semver" %} use _MAJOR_._MINOR_._PATCH_ format for the version of the library ``.dll` and the NuGet package.


Suggested change

{% include requirement/MUST id="dotnet-version-semver" %} use _MAJOR_._MINOR_._PATCH_ format for the version of the library ``.dll` and the NuGet package.

{% include requirement/MUST id="dotnet-version-semver" %} use _MAJOR_._MINOR_._PATCH_ format for the version of the library `.dll` and the NuGet package.

scottaddie · 2025-02-20T20:58:39Z

docs/dotnet/introduction.md


 In the past, [JSON.NET](https://www.newtonsoft.com/json), aka Newtonsoft.Json, was commonly used for serialization and deserialization. Use the [System.Text.Json](https://www.nuget.org/packages/System.Text.Json/)
-package that is now a part of the .NET platform instead.
+package that is now a part of the .NET platform instead. If you are using `Azure.Core`, there is no need for a direct reference to the `System.Text.Json` package.  Your client library will have access to it automatically.


Suggested change

package that is now a part of the .NET platform instead. If you are using `Azure.Core`, there is no need for a direct reference to the `System.Text.Json` package. Your client library will have access to it automatically.

package that is now a part of the .NET platform instead. If you are using `Azure.Core`, there is no need for a direct reference to the `System.Text.Json` package. Your client library will have access to it automatically.

scottaddie · 2025-02-20T20:59:43Z

docs/dotnet/introduction.md

+
+#### .NET Runtime Polyfill Packages
+
+To ensure consistency across runtimes, the Microsoft .NET team publishes polyfill packages on NuGet for some features built into modern .NET runtimes. On runtimes where these features are missing - such as the .NET Framework - the polyfill packages provide them. On runtimes where the features are natively available, the polyfill packages pass through the calls and do nothing.


Suggested change

To ensure consistency across runtimes, the Microsoft .NET team publishes polyfill packages on NuGet for some features built into modern .NET runtimes. On runtimes where these features are missing - such as the .NET Framework - the polyfill packages provide them. On runtimes where the features are natively available, the polyfill packages pass through the calls and do nothing.

To ensure consistency across runtimes, the Microsoft .NET team publishes polyfill packages on NuGet for some features built into modern .NET runtimes. On runtimes where these features are missing, such as .NET Framework, the polyfill packages provide them. On runtimes where the features are natively available, the polyfill packages pass through the calls and do nothing.

scottaddie · 2025-02-20T21:01:00Z

docs/dotnet/refs.md

Suggested change

[.NET Framework Design Guidelines]: https://docs.microsoft.com/dotnet/standard/design-guidelines/

[.NET Framework Constructor Design]: https://docs.microsoft.com/dotnet/standard/design-guidelines/constructor

[.NET Framework Design Guidelines]: https://learn.microsoft.com/dotnet/standard/design-guidelines/

[.NET Framework Constructor Design]: https://learn.microsoft.com/dotnet/standard/design-guidelines/constructor

scottaddie · 2025-02-21T16:35:56Z

docs/dotnet/introduction.md

@@ -1089,22 +1071,96 @@ Use _-beta._N_ suffix for beta package versions. For example, _1.0.0-beta.2_.

 {% include requirement/MUST id="dotnet-version-change-on-release" %} select a version number greater than the highest version number of any other released Track 1 package for the service in any other scope or language.

+### Target Frameworks
+
+All Azure SDK libraries must include a target for [.NET Standard 2.0].  This ensures that they are compatible with all supported versions of .NET, covering both modern .NET and the .NET Framework.  


Suggested change

All Azure SDK libraries must include a target for [.NET Standard 2.0]. This ensures that they are compatible with all supported versions of .NET, covering both modern .NET and the .NET Framework.

All Azure SDK libraries must include a target for [.NET Standard 2.0]. This ensures that they are compatible with all supported versions of .NET, covering both modern .NET and the .NET Framework.

scottaddie · 2025-02-21T16:36:56Z

docs/dotnet/introduction.md

+
+Libraries built by the Azure SDK engineering system will also target the oldest supported [long term support (LTS)] version of .NET. This enables them to take advantage of modern runtime features, allows applications to fully benefit from modern runtimes, and obviates the need for applications to download polyfill shim packages for functionality already built-into modern runtimes. It is strongly encouraged that self-published libraries also include this target framework.
+
+For projects built by the Azure SDK engineering system, use the following target setting is in the `.csproj` file:


Suggested change

For projects built by the Azure SDK engineering system, use the following target setting is in the `.csproj` file:

For projects built by the Azure SDK engineering system, use the following target setting in the `.csproj` file:

jsquire added .NET Docs labels Feb 18, 2025

jsquire added this to the 2025-03 milestone Feb 18, 2025

jsquire requested review from christothes and scottaddie February 18, 2025 18:16

jsquire self-assigned this Feb 18, 2025

Fixing typos

8039993

jsquire commented Feb 18, 2025

View reviewed changes