[Feature]: Create More Consumable Library Interfaces (or SDK Documentation, or both!)

[Insomniak47]

NuGet Product(s) Involved

Nuget SDKs

The Elevator Pitch

The Nuget libraries are real dense to get into and the API surface makes it harder to design tools that are built on top of nuget and the common nuget abstractions that someone might want to use. It would be nice if we could make some common workflows that people might want to use more user friendly. Alternatively it might just be a documentation thing and a simple documentation push to add examples of common use etc might also help.

Examples from my own experience:

• Package Version resolution from sln/csproj files
• Listing and walking dependency trees
• Adding package references to existing projects

Additional Context and Details

This comes from something I've been trying to take a look at recently related to pinning some transitive dependencies. I've taken a peek through the source for a few hours to try and see the common-ish methods for resolving things like dependency versions or even just determining the source of a dependency and it just seems a bit heavier of a job than I would have expected. It would be awesome (and I'd love to contribute) to exposing or documenting some of this functionality from the Nuget.Core libs in a way that doesn't require a huge deep dive to be able to use.

From a cost/benefit obviously there's the issue of additional maintenance and testing but the tradeoff would be that it would help build up the tooling ecosystem around nuget and might make contribution easier.

It seems that there are a few issues tagged under the SDK area that would fall under this umbrella:

#6188
#8126
#10430

[Insomniak47]

Hey all, if someone could give me a summary of some of the concerns or main classes for some of the mentioned features that I should look at to do this I'm happy to come up with a quick POC better demonstrating it.

[Insomniak47]

Hey I know @JonDouglas is on Pat leave right now so I don't want this to stale out. I'm still interested and coming up on a hackathon at the middle of the month that would give me a decent amount of extra time to work on a POC.

[Insomniak47]

@JonDouglas just another bump here - not trying to be annoying. Just starting that company sponsored hackathon rn so would be a great time to be able to take this on as a POC provided I can get some info on where to start.

[JonDouglas]

Hey @Insomniak47,

Thanks for the feature request! We absolutely love the idea, however I do want to be a bit transparent.

The NuGet SDKs are typically a by-product of all the work we do shipping the client & surrounding tooling. This means that the SDK documentation, user experience, APIs, and more may lack in comparison to the user facing experiences(nuget.exe, dotnet CLI, Visual Studio, etc).

See https://github.com/NuGet/NuGet.Client/blob/dev/docs/nuget-sdk.md for a little more context on this.

We really want to improve our SDK story in every way we can. There are some larger gaps like you mentioned in this issue, and we can use as much help as we can get in improving this such as documenting our SDK libraries, creating conceptual docs when using those libraries, creating getting started READMEs, and so on.

If you'd like to make any contributions such as documentation to our various repos such as the NuGet SDKs, NuGet docs, and more, we would gladly look over any PRs. For any changes to NuGet SDK or APIs, please consider writing up a NuGet design proposal so we can review before you commit to making any large changes.

Feel free to tag one of us on the various issues or PRs for what you're thinking of contributing & we'll assist however we can.

[Insomniak47]

@JonDouglas that sounds good, is there any way I could get some insight into some of the main pathways for walking dependencies etc? I'd like to get it going but each command seems to do it in different ways or have some nuance that isn't obvious as an external party. Do you guys have a slack or a discord I could pop in on and chuck low pri questions at you or is there someone I can @ in this issue?

I'm pretty interested in doing this because we lose a lot of time to tracking down the different things we need to fix in transitive vulns etc so I can invest a ton of time and still end up net positive.

re: design proposal. I'd like to iterate a bit on a POC before I start making any concrete proposals. I'm sure there's a ton of institutional knowledge I'm lacking that would make anything I propose right now to naive to be useful and I'd rather come at it with enough of an understanding that I'm not wasting everyone's time

[JonDouglas]

@Insomniak47 We have a discord channel as part of the .NET Evolution discord. We also have discussions enabled on the repo. These are mostly community-driven forums but there's usually a few team members inside or other community members that may be able to help further.

I'm not aware of much documentation that will bring quick insight to walking dependencies. It's a complex code area and works in mysterious ways 😆 .

It may be a good starting point to look at how dependencies are resolved in code/tests for your respective scenarios & reading our docs on the topic:

https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution

No worries on taking your time. When you're ready to submit, please feel free or let me know if you have any questions.