PackageReferences: Dependency Management for lib authors

[rcollina]

Hi!
I've been working on a set of internal libraries for our company, they mostly build upon M.E.DI, M.E.L, etc.

Scenario
Let's say I have a library named MyCompany.Microsoft.Extensions.Hosting.
This library depends on Microsoft.Extensions.Hosting version 3.1.3.

I've been trying to figure out how to properly <PackageReference /> Microsoft.Extensions.Hosting to prevent conflicts with other libraries and applications depending on the same Extensions package.
I'd also like to know if I need to repackage my own library each time a new Patch version is out (3.1.4, for instance), or if there's a smart way to avoid this.

M.E.H is an example, I think the same holds for any third-party dependency really.

I could use some guidance here, as getting it wrong would imply several downstream issues for our internal customers.

What I've tried
In MyCompany.Microsoft.Extensions.Hosting.csproj each third-party PackageReference has a both PrivateAssets="all" and a Version Range.

    <PackageReference Include="Microsoft.Extensions.Hosting"
                      Version="[3.1.3, 4.0.0)"
                      PrivateAssets="all"/>

• PrivateAssets forces consumers to reference M.E.H instead of having it transitively imported in their project.
• The Version Range is nasty - what version am I really building against? That was my attempt to provide bounds for the supported versions in the nupkg definition.

Some guidance on how to approach this in a sustenable manner would be immensely beneficial.
Thanks!

[Pilchie]

@DamianEdwards do you know if anything ever got written up for this?

One question is - does your package .NET Framework as well as .NET Core (either via .NET Standard, or via multi-targeting)? If it just references .NET Core then in general you shouldn't need to have an explicit dependency for anything that is in the ASP.NET Core shared framework.

[rcollina]

@Pilchie I forgot to mention they mostly are .NET Standard 2.1 libraries. No multitargeting planned.
I do have one netcoreapp3.1 library, csproj is as follows:

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

[rcollina]

Hello @Pilchie
While waiting for some guidance I did try to figure out Microsoft’s own build, versioning and cross-repo coordination strategies.
Sadly it’s something I can’t possibly tackle on my own.
Any help would be truly appreciated.

[shirhatti]

@tarekgh @maryamariyan We need to figure guidance for library authors here.
This is the same ask that @cijothomas on what version of M.E.L the OpenTelemetry libraries can rely on?

[tarekgh]

@rcollina @shirhatti

The packages we are releasing for net5.0 is supporting netstandard 2.0/2.1 so depending on the M.E.H package version 5.0.0 should satisfy your library requirement and you will be on latest. If the app using your library is using different M.E version, the resolver will pick the version that satisfy both the app and your library according to the rules mentioned https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution.

For OTel, we need to know the minimal targeting requirement. The net5.0 packages support NETFX version 4.6.1. If OTel need to use lower than that we can talk about it. but at least we need to get the minimal requirements.

For new written/compiled Libraries, I suggest to use v5.0.0 of such packages.

The question now, is there any issue if you depend on M.E. v5.0?

CC @noahfalk @ericstj

[shirhatti]

The question now, is there any issue if you depend on M.E. v5.0?

We have breaking changes between major versions of M.E.*.
Take a look at this for example- https://www.fuget.org/packages/Microsoft.Extensions.Hosting.Abstractions/3.1.8/lib/netstandard2.0/diff/2.1.1/

If another dependency in your app relies on any of these APIs, you could end up with all sorts of issues at runtime

[ericstj]

We have breaking changes between major versions of M.E.*.

We shouldn't do that moving forward: we do not allow such changes in dotnet/runtime.

The general best-practice for all libraries is to use normal PackageReferences, reference every library that you directly consume, and do not declare an upper bound. This is the most tolerant and declares the dependencies needed by your library. In the case of extensions, I'd also reccomend that libraries use PackageReferences instead of FrameworkReferences as it permits your library to be used in console apps. The additional PackageReferences will be handled by the SDK.

[tarekgh]

I agree we cannot tolerate such breaking changes especially when removing or changing the already exposed APIs. Considering this breaking change between 2.1.1 and 3.1.8 already occurred, there is no good solution to guarantee all scenarios will work. so our guidelines will be for moving forward. I am still recommending using v5.0 of the package. We should document the broken scenario when apps/libs using 2.1.1 or lower can run into the breaking scenario and we should recommend them to upgrade to v5.0 too.

[rcollina]

Hello everyone,
Now that the .NET SDK 5.0.100 is out, I'd like to know if I can reference 5.* packages in my .NET Standard 2.1 libraries and still be .NET Core 3.1 compatible (I believe so, but please correct me if I'm wrong).

fuget.org seems to corroborate this.

[tarekgh]

@rcollina, yes you can reference such package and it should work fine with .net core 3.1 too. The package is targeting ns 2.0 and 2.1 and netfx 4.6 which should work fine with net core 3.1. Please let's know if you face any problem when using it.

[rcollina]

@tarekgh thank you, I'll give it a try and hopefully get back to you with good news.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[ghost]

Tagging subscribers to this area: @eerhardt, @maryamariyan
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Hi!
I've been working on a set of internal libraries for our company, they mostly build upon M.E.DI, M.E.L, etc.

Scenario
Let's say I have a library named MyCompany.Microsoft.Extensions.Hosting.
This library depends on Microsoft.Extensions.Hosting version 3.1.3.

I've been trying to figure out how to properly <PackageReference /> Microsoft.Extensions.Hosting to prevent conflicts with other libraries and applications depending on the same Extensions package.
I'd also like to know if I need to repackage my own library each time a new Patch version is out (3.1.4, for instance), or if there's a smart way to avoid this.

M.E.H is an example, I think the same holds for any third-party dependency really.

I could use some guidance here, as getting it wrong would imply several downstream issues for our internal customers.

What I've tried
In MyCompany.Microsoft.Extensions.Hosting.csproj each third-party PackageReference has a both PrivateAssets="all" and a Version Range.

    <PackageReference Include="Microsoft.Extensions.Hosting"
                      Version="[3.1.3, 4.0.0)"
                      PrivateAssets="all"/>

• PrivateAssets forces consumers to reference M.E.H instead of having it transitively imported in their project.
• The Version Range is nasty - what version am I really building against? That was my attempt to provide bounds for the supported versions in the nupkg definition.

Some guidance on how to approach this in a sustenable manner would be immensely beneficial.
Thanks!

Author:	rcollina
Assignees:	-
Labels:	area-Extensions-Hosting
Milestone:	-

[tarekgh]

@shirhatti this issue has the information for guidance. We recommend using the version 5.0+ of the libraries. Users using older versions may need to consider migrating to 5.0 for better support (and we may need to find the data for the old breaking changes done in 2.1). Where can this guideline live? is it something you can help documenting it? should we move this issue to the doc repo? Thanks!

[shirhatti]

Before we move this to docs, we should be sure we don't plan to any product work here.

As an example, we could add an analyzer for library authors to avoid depending on public API that we broke? I'd like to see how much API surface we broke across all of Microsoft.Extensions.* before making this decision as this isn't just a logging concern

[tarekgh]

My understanding is in 5.0 we didn't introduce any break like the one introduced in 2.1. Does your ask concern all extension versions? or are you talking about moving from 3.1 to 5.0 breaking?

[eerhardt]

@maryamariyan @tarekgh - what are the next steps here?

I don't think we need to write an analyzer to ensure old APIs aren't being used. The old versions are EOL in a month (2.1 will no longer be supported). We won't be making breaking changes in the M.E.* libraries going forward, so we don't need to worry about this in the future.

I believe our guidance for these packages remains the same as guidance for any NuGet dependency - so if some documentation needs to be written, it is broader than Microsoft.Extensions.*.

Basically, I believe this issue can be closed.

[tarekgh]

2.1 will no longer be supported

I don't think this is true for asp.net because of ASP.NET Core 2.1 used on .NET Fx :-(

@shirhatti offline mentioned The guidance can be simplified to rely on the oldest supported Abstractions package if you are Core only. And there's no good solution if you're on .NET Fx