Global tools - Part 1 #5036
Global tools - Part 1 #5036
Conversation
|
|
||
| `-f|--framework <FRAMEWORK>` | ||
|
|
||
| Specifies the [target framework](../../standard/frameworks.md) to install the tool for. |
There was a problem hiding this comment.
when does someone need to specify this @KathleenDollard?
There was a problem hiding this comment.
no, not until a breaking runtime came out.
Producers can construct packages targeting multiple TFMs, say, a single package with a tool for netcoreapp2.1 and netcoreappVNEXT. Or even produce a package with a TFM different from the one used in the CLI.
The CLI utilize NuGet to pick the fittest TFM. The CLI has the notion of a bundled TFM, which indicates the TFM that the CLI itself targets. CLI will always pass that TFM to NuGet and NuGet will write asset file with filtered TFM. CLI does not prob the disk, instead it finds asset by reading the asset file.
This approach does not work when the tool is packaged with netcoreapp and say net46, because the CLI will always pick the netcoreapp TFM. In order to work around this, the consumer will have to provide the TFM to install the command. Note that this should not be a problem if the package contains only the net46 TFM.
Also, when the user has the 2.1 CLI installed and then installs the 2.1 runtime, the 2.1 version of the tool will continue to be selected, as that’s the CLI bundled version. But the user can obtain the netcoreapp3.0 version of tool by specifying TFM in the command line. Again using the escape hatch we defined above. We use the TFM bundled version because it has the highest likelihood of succeeding, since that tool will target the runtime that the CLI itself is using to run.
There was a problem hiding this comment.
@wli3 Shall we add something like
"For .NET Core 2.1 this switch is rarely needed."
There was a problem hiding this comment.
Ok, I understand the concept that inside the package, you can have multiple TFMs supported and by specifying this, you can effectively select one. But it would be good to add to the command description, some concise explanation of why you might need to specify this. the netcoreapp and other TFMs, for example, seems like a good scenario. Or maybe an explanation that CLI will try to choose the best TFM for you, so you rarely need this?
There was a problem hiding this comment.
Whatcha' think about this:
While most Global Tools are not framework specific, framework specific tools are supported. If a framework is specified, it is used to select the correct version of the tool. If a framework is not specified, the framework of the currently running .NET SDK is used.
The framework is specified via its TFM, which you can find here.
In most cases, you do not need the --framework switch.
There was a problem hiding this comment.
"While most Global Tools are not framework specific, framework specific tools are supported"
This is kind of wrong. All tools are TFM specific. But you can multi target. And we only support netcoreapp2.1. Maybe
"SDK will try to choose most appropriate TFM by default . However, this can be overwritten by this flag""
|
|
||
| `--version <VERSION_NUMBER>` | ||
|
|
||
| The version of the tool to install. By default, the latest stable package version is installed. |
There was a problem hiding this comment.
Add something like
"Use the --version switch to install preview versions."
|
|
||
| `PACKAGE_ID` | ||
|
|
||
| ID of the NuGet package that contains the .NET Core Global tool to install. |
There was a problem hiding this comment.
Is it worth mentioning that the PACKAGE_ID is the same as the package name?
There was a problem hiding this comment.
I was actually thinking if I should use PACKAGE_NAME instead. PACKAGE_ID is what shows up in --help. We already use PACKAGE_NAME in the NuGet commands. So I think it's better to switch and then I'll switch on --help when I finally have a chance to review the strings and all.
docs/core/tools/dotnet-tool-list.md
Outdated
|
|
||
| `-g|--global` | ||
|
|
||
| Specifies that the tool to be removed is from a user-wide installation. If you don't specify this option, you must specify the `--tool-path` option. |
There was a problem hiding this comment.
Copy and paste error: List doesn't remove a tool, does it?
There was a problem hiding this comment.
Yes, copy and paste error 😢
|
|
||
| * Find information about the tool (usually a website or GitHub page). | ||
| * Check the author and statistics in the home for the feed (usually NuGet.org). | ||
| * Install the tool. |
There was a problem hiding this comment.
uninstall is also an option, right?
|
|
||
| Installs version 1.0.0 of the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: | ||
|
|
||
| `dotnet tool install -g dotnetsay --version 1.0.0` |
There was a problem hiding this comment.
Change to 2.0.0 since 1.0.0 is broken due to Preview 2 changes.
docs/core/tools/dotnet-tool-list.md
Outdated
|
|
||
| `-g|--global` | ||
|
|
||
| Specifies that the tool to be removed is from a user-wide installation. If you don't specify this option, you must specify the `--tool-path` option. |
There was a problem hiding this comment.
Remove "to be removed". Something like:
"Specifies that the list be from the user-wide installation....
docs/core/tools/dotnet-tool-list.md
Outdated
|
|
||
| `--tool-path <PATH>` | ||
|
|
||
| Specifies a custom location where to find global tools. PATH can be absolute or relative. Can't be combined with the `--global` option. |
There was a problem hiding this comment.
Parallel the -g text.
Also: If this isn't specified, the -g switch should be
There was a problem hiding this comment.
Also, --g required if this isn't included.
|
|
||
| `--tool-path <PATH>` | ||
|
|
||
| Specifies the location where to install the global tool. PATH can be absolute or relative. If PATH doesn't exist, the command tries to create it. Can't be combined with the `--global` option. |
There was a problem hiding this comment.
Perhaps
"If you don't specify this option, you must specify the --global option.
|
|
||
| ## Examples | ||
|
|
||
| Installs the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: |
There was a problem hiding this comment.
add similar to
"in the default location"
|
|
||
| `PACKAGE_ID` | ||
|
|
||
| ID of the NuGet package that contains the .NET Core Global tool to uninstall. |
There was a problem hiding this comment.
Maybe add
"You can find the package ID using the dotnet tool list command.
|
|
||
| `--tool-path <PATH>` | ||
|
|
||
| Specifies the location where to uninstall the global tool. PATH can be absolute or relative. Can't be combined with the `--global` option. |
There was a problem hiding this comment.
Do same as in other commands regarding -g required if this not used.
|
|
||
| `PACKAGE_ID` | ||
|
|
||
| ID of the NuGet package that contains the .NET Core Global tool to update. |
There was a problem hiding this comment.
Perhaps: Consistent with uninstall, suggest list to find package ID
|
|
||
| `--tool-path <PATH>` | ||
|
|
||
| Specifies the location where the global tool is installed. PATH can be absolute or relative. Can't be combined with the `--global` option. |
There was a problem hiding this comment.
Consistent with others, if you don't include -g required
There was a problem hiding this comment.
We aren't consistent with how we cap "global tools" in different parts. I didn't help within the body of my comments.
I've followed Rich's lead and caps, but if the standard for docs is lower case, I have no problem with that. Might loop in @richlander on that.
docs/core/tools/global-tools.md
Outdated
|
|
||
| You can find .NET Core Global Tools on [NuGet](https://www.nuget.org). However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools. | ||
|
|
||
| You may also find tool recommendations in blog posts. |
There was a problem hiding this comment.
Can we include an external link here. Nate McMaster has compiled a list.
docs/core/tools/global-tools.md
Outdated
|
|
||
| ## Check the author and statistics | ||
|
|
||
| Since .NET Core Global Tools run in full trust and are installed on your path, they can be very powerful. Don't download tools from people you don't trust. |
There was a problem hiding this comment.
"are generally installed...
docs/core/tools/global-tools.md
Outdated
| If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool. | ||
|
|
||
| ## Install a global tool | ||
|
|
There was a problem hiding this comment.
Either here or at the end of the section let's talk about location. This a suggestion for this location, but I'm not sure whether this is best here or somewhat different text at the end.
"Global tools can be installed in the default directory or in a specific location. The default directories are:
| OS | Path |
|---|---|
| Linux/macOS | $HOME/.dotnet/tools |
| Windows | %USERPROFILE%\.dotnet\tools |
These locations are added to the user's path when the SDK is first run, so global tools installed there can be called directly.
Global tools can also be installed in a specific directory. When installed in a specific directory, the user must ensure the command is available, by including that directory in the path, by calling the command with the directory specified, or calling the tool from within the specified directory.
There was a problem hiding this comment.
Yes, this info was missing and I was adding something to that extent. Went with your suggestion.
docs/core/tools/global-tools.md
Outdated
|
|
||
| ## Install a global tool | ||
|
|
||
| To install a global tool, you use the [dotnet tool install](dotnet-tool-install.md) .NET Core CLI command like in the following example: |
There was a problem hiding this comment.
"tool in the default directory, you use
|
|
||
| Once the tool is installed, you can call it by using its command. Note that the command may not be the same as the package name. | ||
|
|
||
| If the command is `dotnetsay`, you call it with: |
There was a problem hiding this comment.
Some variation of
", and it was installed with the --global switch, you
There was a problem hiding this comment.
well, whether it's global or not, you'd still use the same command no? you just might have to specify the path depending on where you are
There was a problem hiding this comment.
Right, I'm fine leaving this as is.
docs/core/tools/global-tools.md
Outdated
| ``` | ||
|
|
||
| You can find which tools are included in an installed Global Tool package by listing the installed packages. | ||
|
|
There was a problem hiding this comment.
dotnet tool list -g
docs/core/tools/global-tools.md
Outdated
|
|
||
| * An application rolls forward to the highest patch release of the specified major and minor version. | ||
| * If there is no matching runtime with a matching major and minor version number, the next higher minor version is used. | ||
| * Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. |
There was a problem hiding this comment.
"Thus, Global Tools created during the preview must be rebuilt and republished by the author and reinstalled.
There was a problem hiding this comment.
- Additional issues can occur with Global Tools created in .NET Core 2.1 Preview 1. Please see the .NET Core 2.1 Preview 2 Known Issues
| ``` | ||
|
|
||
| Contact the author of the Global Tool and see if they can recompile and republish their tool package to NuGet with an updated version number. Once they have updated the package on NuGet, you can update your copy. | ||
|
|
There was a problem hiding this comment.
There is a special problem with Preview 1 tools. They must be manually uninstalled, and will give errors if you try to update. It is especially ugly because you can git "doesn't exist" on uninstall and "can't install cause it exists" on install.
The fix is in the release notes, but since it's so nasty, do we need something here as well?
There was a problem hiding this comment.
I'm adding a warning. You might eventually be able to remove it after we're past RTM.
There was a problem hiding this comment.
This isn't quite right. I added a note elsewhere that we probably want this warning in uninstall and update. Probably also here.
Uninstall fails and you must go to the directories to delete
Therefore Update fails
"If you installed Global Tools that were built with .NET Core 2.1 Preview 1 release, there's a known issue where you must manually uninstall these tools. Neither uninstall or update will work. For information on removing Preview 1 global tools, see .NET Core 2.1 Preview 2 Known Issues.
|
I've addressed all the feedback and added some additional info from @natemcmaster's blog post. Let m,e know if you see anything wrong with my changes. /cc @KathleenDollard |
|
@BillWagner I think this is ready for a final review. There's more work to be done in the future. |
docs/core/tools/dotnet-tool-list.md
Outdated
|
|
||
| ## Name | ||
|
|
||
| `dotnet tool list` - Lists all [.NET Core Global Tools](global-tools.md) currently installed on your machine or specified path. |
There was a problem hiding this comment.
Current text could be read: All global tools installed anywhere on your machine.
"currently installed in the default directory on your machine or specified path.
docs/core/tools/dotnet-tool-list.md
Outdated
|
|
||
| ## Description | ||
|
|
||
| The `dotnet tool list` command provides a way for you to list all .NET Core Global Tools installed on your machine (current user profile) or specified path. The command lists the package name, version installed, and the global tool command. To use the list command, you either have to specify that you want to see all user-wide tools using the `--global` option or specify a custom path using the `--tool-path` option. |
There was a problem hiding this comment.
same problem as above. Alternative resolution:
"list all .NET Core Global Tools installed user-wide on your machine (current user profile) or in the specified path
docs/core/tools/dotnet-tool-list.md
Outdated
|
|
||
| ## Examples | ||
|
|
||
| Lists all Global Tools installed in your machine (current user profile): |
There was a problem hiding this comment.
Same problem. Suggest
"installed user-wide on
docs/core/tools/dotnet-tool-list.md
Outdated
|
|
||
| `dotnet tool list -g` | ||
|
|
||
| Lists the sample Global Tools from a specific Windows folder: |
|
|
||
| ## Examples | ||
|
|
||
| Uninstalls the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: |
There was a problem hiding this comment.
Maybe drop "sample" here and below
|
|
||
| ## Examples | ||
|
|
||
| Updates the [dotnetsay](https://www.nuget.org/packages/dotnetsay/) sample Global Tool: |
There was a problem hiding this comment.
Maybe drop "sample" here and below
|
|
||
| Once the tool is installed, you can call it by using its command. Note that the command may not be the same as the package name. | ||
|
|
||
| If the command is `dotnetsay`, you call it with: |
There was a problem hiding this comment.
Right, I'm fine leaving this as is.
| `--tool-path <PATH>` | ||
|
|
||
| Specifies the location where to uninstall the global tool. PATH can be absolute or relative. Can't be combined with the `--global` option. If you don't specify this option, you must specify the `--global` option. | ||
|
|
There was a problem hiding this comment.
We should probably add a warning about uninstall not working on Preview 1 tools. Let's get the other warning right and then see what should go here. Similar warning should probably go in update.
There was a problem hiding this comment.
Given that we're only shipping these docs now and we don't usually cover preview issues on those unless it's the current functionality, I'm not going to address this comment. But please let me know if you still feel this is needed.
| ``` | ||
|
|
||
| Contact the author of the Global Tool and see if they can recompile and republish their tool package to NuGet with an updated version number. Once they have updated the package on NuGet, you can update your copy. | ||
|
|
There was a problem hiding this comment.
This isn't quite right. I added a note elsewhere that we probably want this warning in uninstall and update. Probably also here.
Uninstall fails and you must go to the directories to delete
Therefore Update fails
"If you installed Global Tools that were built with .NET Core 2.1 Preview 1 release, there's a known issue where you must manually uninstall these tools. Neither uninstall or update will work. For information on removing Preview 1 global tools, see .NET Core 2.1 Preview 2 Known Issues.
|
Sure @KathleenDollard, we can wait. Somehow I thought you wanted the link for the aka.ms/global-tools live ASAP. I was also wondering about the capitalization of Global Tools that you mentioned earlier. Did @richlander say anything? |
| @@ -0,0 +1,166 @@ | |||
| --- | |||
| title: .NET Core Global Tools | |||
There was a problem hiding this comment.
Question about naming (for @livarcocc @KathleenDollard). At one point, I remember us saying we wanted to call this feature ".NET Core tools" because 'global' is just one way to install the tool, but not the only one. Am I remembering right? Has the thinking changed? Or have we settled on calling this feature ".NET Core Global Tools"?
There was a problem hiding this comment.
We've had pretty universal stickiness on .NET Core Global Tools and I think we should let that ride to avoid confusion with a new feature. We can differentiate "Repo" (or "Project") tools if they behave differently.
docs/core/tools/global-tools.md
Outdated
| If the tool author wanted the tool to appear in the context of the `dotnet` prompt, they may have written it in a way that you call it as `dotnet <command>`, such as: | ||
|
|
||
| ```bash | ||
| dotnet ef |
There was a problem hiding this comment.
This example doesn't exactly match with what you are describing. dotnet ef is now a built-in command. A better example of this would be dotnet serve or @spboyer's dotnet doc
There was a problem hiding this comment.
Great catch. Let's use dotnet doc
|
@mairaw We are changing --source-feed to --add-source and removing -f. Neither --framework or --add-source will have an abbreviation. This implementation is still working its way through repos. I think that finishes up my input on this version. @natemcmaster yes there will be a separate doc for creation. |
mairaw
modified the milestones:
Sprint 134 (4/7/2018 - 4/27/2018),
Sprint 135 (4/28/18 - 5/18/18)
|
Re |
|
@KathleenDollard, could this move forward if the name was settled? I will then update manpages in cli repo so Unix like OS packages can get updated docs packed by RTM. Thanks! |
docs/core/tools/global-tools.md
Outdated
|
|
||
| [!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] | ||
|
|
||
| .NET Core Global Tools are a special NuGet package that contains a console application. A Global Tool can be installed on your machine on a default location that is specified in the PATH environment variable or on a custom location. |
There was a problem hiding this comment.
[…] Tools are a […] package that contains a […] application
I think the grammatical number here is not correct. I think it would make sense to put everything in singular:
A .NET Core Global Tool is a special NuGet package that contains a console application.
docs/core/tools/global-tools.md
Outdated
|
|
||
| [!INCLUDE [topic-appliesto-net-core-2-1plus.md](../../../includes/topic-appliesto-net-core-2-1plus.md)] | ||
|
|
||
| .NET Core Global Tools are a special NuGet package that contains a console application. A Global Tool can be installed on your machine on a default location that is specified in the PATH environment variable or on a custom location. |
There was a problem hiding this comment.
A Global Tool can be installed on your machine on a default location that is specified in the PATH environment variable […]
This could be read as if PATH is used to specify where a Tool is installed. Maybe change it to:
A Global Tool can be installed on your machine on a default location that is included in the PATH environment variable […]
| * Uninstall the tool. | ||
|
|
||
| > [!IMPORTANT] | ||
| > .NET Core Global Tools appear on your path and run in full trust. Do not install .NET Core Global Tools unless you trust the author. |
There was a problem hiding this comment.
What's "full trust"? AFAIK, that's a .Net Framework concept that does not exist in .Net Core.
There was a problem hiding this comment.
@KathleenDollard can you comment here? Can't recall if I got that from you or not. The way I read this is that the app would have access to everything on your computer include registry, log files, etc.
docs/core/tools/global-tools.md
Outdated
|
|
||
| ### What could go wrong | ||
|
|
||
| Global Tools are shared framework applications, which means they rely on a .NET Core runtime installed on your machine. If the expected runtime is not found, they follow normal .NET Core runtime roll-forward rules such as: |
There was a problem hiding this comment.
What's a "shared framework application"? Do you mean "framework-dependent application"?
There was a problem hiding this comment.
I believe you're correct @svick. Also @KathleenDollard I've heard that we were having some confusion with the roll-forward terminology. Should we still use that here? /cc @nguerrera @johnbeisner
|
@BillWagner @JRAlexander @rpetrusha can one of you review and approve this one? |
|
Yes, we can move this onward |
Related to #4627 and #4509
@KathleenDollard I've used your gist to get this started but I think there's more work to do here. But see if this looks good for a first version, so we can have some docs out.
Internal review URLs:
dotnet tool install
dotnet tool uninstall
dotnet tool update
dotnet tool list
Global Tools