Add a dotnet-ref command to enable adding references to the project file

[blackdwarf]

The CLI needs to provide a way for users to add project and package references to the project file.

Below is a mini-spec of the command.

Note: this is a mini-spec, more detailed documents will be available on docs.microsoft.com

Usage

dotnet &lt;operation&gt; <project_or_solution> &lt;command&gt; &lt;project_or_package&gt; <args>

Operations

• add
• list
• remove
• update

Commands

• project
• package

Arguments

• <operation>
  • One of the operation from the previous list
• <command>
  • One of the commands from the above list
• <project_or_solution>
  • A project or a solution path
• <project_or_package>
  • Path to the project file to include in the project or a package ID for package references
• <args>
  • Arguments to the command

Defaults

• If the <project> is not present, we will try to see if there is a project in the current directory; if there is, it will be added, if not, an error is displayed
• If the <project_or_solution> is not present, we will check the current directory for either a project file or a sln file.
  • If neither are found, an error is displayed
  • If more than one is found or if there is both sln and a project file present, an error is displayed prompting the user to specify which file the operation should work on.

Arguments

Arguments are here mostly for the package command. Arguments are the following:

• --version | -v - provides a version for the package to be added. If none is specified, latest is assumed.
• --pre-release | -p - specify whether to check for pre-release packages as well.
• --frameworks | -f - place the package reference under the specified framework.
• --no-restore | -n - do not restore after the operation completes.

Notes

• This command adds a project to a solution if it works on an SLN file. In case a project file, it will add a <ProjectReference> to the project in question.
• The command will make absolute paths of the project being added relative to the solution file/project being added. This is done to avoid messy breaks when moving machines.

Examples

• dotnet add project "../path/to/project.csproj"
  • Add a project found at the specified path to the project file
• `dotnet remove package Newtonsoft.json
  • Remove a package with the specified ID
• dotnet add package package.id --version 1.0.0
  • Add the package with package ID of "package.id" with the specified version.
• dotnet list path/to/project.csproj package
  • List out all of the packages in the specified project file

[dasMulli]

It would be awesome to also have a sub-verb to update NuGet references / show if an update is available.

[wjk]

Honestly, I don't see a need for a specialized command just to add a <PackageReference> tag to the csproj; I do it by hand and have no problems. On the other hand, @dasMulli's suggestion about a command to update NuGet references is a great idea.

[Ziflin]

@wjk It is a very useful feature of NodeJS to be able to install/uninstall a package from the command line for certain build systems. I would imagine it would be equally useful in dotnet.

[dasMulli]

this command will not put TFM-specific dependencies in the project file. For that, a manual edit will have to be done

I think if it did support TFM-specific references, this would be highly useful since adding a PackageReference is easy, but getting the condition right from memory not so much (srsly, "do i need to wrap things with apostrophes? do i need brackets for the $xyz expressions? what was that variable called again anyway?")

For adding references, a switch could be added for the target framework:

• --framework | -f
  Specify for which target framework the reference shall be added to.

Use cases:

• dotnet ref add Microsoft.AspNetCore.Hosting.WindowsServices -f net462
• dotnet ref add Microsoft.NETCore.App -v 1.1.0 -f netcoreapp1.1

Logic could be (design needed):

1. If the package is already in a general ItemGroup, fail with an error.
2. If there is a PackageReference item with the required condition in a general ItemGroup, fail with an error.
3. If the package is already in an item group with a TFM condition on the specified framework, fail with an error.
4. Find or create an ItemGroup with the necessary TFM condition, add a PackageReference there.

If VS "15", NuGet 4.* VSIX already has logic for that, it could be "borrowed".

(Same applies to projects / ProjectReference)

[blackdwarf]

Tracking issue is dotnet/cli#4746

[enricosada]

It's possible to add also an option to set also PrivateAssets property for PackageReference?
it's useful for adding sdk packages who need <PrivateAssets>All</PrivateAssets>

So something like --private-assets "All" ?
@blackdwarf if ok, i can add that (i need that for adding fsharp sdk package :D, so personal interests) but i think is useful for scripting/tutorial to add dotnet test sdk packages
So like

• create console with dotnet new
• add ref to xunit/nunit sdk
• add ref to xunit/nunit packages
• go!

[TheRealPiotrP]

@enricosada I like the proposal. Can you wait on dotnet/cli#4758? We decided to change the calling convention for this class of commands to get back to dotnet {verb} {subject} {object} behavior and @krwq is making fairly big code changes to account for that. Once it's merged, we'll have a basis for other commands including adding package refs and the private flag.

@rrelyea I believe this ask, having a verb to add a nuget package reference and marking it All<... might be interesting to you.

[TheRealPiotrP]

@dasMulli Can you open an issue in nuget/home to track the PackageRef update verb you propose?

[TheRealPiotrP]

@blackdwarf can you update the docs at the top to match the current POR for impl?

[enricosada]

Honestly, I don't see a need for a specialized command just to add a tag to the csproj; I do it by hand and have no problems

the command is for cli, but is also useful because you can automate things (from ide/tools or script).

• dotnet new
• dotnet ref add Newtonsoft.Json
• copy Program.fs serializator example
• dotnet run

[krwq]

dotnet add p2p dotnet remove p2p and dotnet list p2ps are already here. Dlls are out of scope. Packages are done by NuGet team.

@piotrpMSFT, can we close this? We already have https://github.com/dotnet/cli/issues/4746

[TheRealPiotrP]

Yea, dotnet add p2p is done.

@enricosada make sure the add ref features you're asking for get logged in nuget/home.