Document dotnet tools plugin usage #3379

Nigusu-Allehu · 2024-12-06T00:21:03Z

learn-build-service-prod · 2024-12-06T00:22:09Z

Learn Build status updates of commit 18ce1c9:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

Try searching the learn.microsoft.com contributor guides
Post your question in the Learn support channel

learn-build-service-prod · 2024-12-06T00:32:59Z

Learn Build status updates of commit eba36da:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

Try searching the learn.microsoft.com contributor guides
Post your question in the Learn support channel

learn-build-service-prod · 2024-12-06T00:34:50Z

Learn Build status updates of commit 7de8612:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

Try searching the learn.microsoft.com contributor guides
Post your question in the Learn support channel

nkolev92 · 2024-12-06T00:48:52Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+
+1. Plugins installed as .NET tools must follow a naming convention: **`nuget-plugin-*`**.
+2. Upon installation, these plugins are added to the `PATH` by the .NET SDK. NuGet scans the `PATH` environment variable for executables with names starting with `nuget-plugin-`.
+3. On Windows, NuGet looks for `.exe` or `.bat` files, while on Linux and macOS, it identifies plugins by checking for the executable bit.


Is this in addition to #1?

So how does one ship a global tool that works on both linux & windows?

Sorry I was confused about this because I clicked on #1 and it ssays 47 files changed, and I couldn't figure out how it was related to this PR. Now, I understand you meant to ask about bullet point number 1. Yes, all dotnet tool plugins are expected to follow the naming conventions in number 1. Shipping a global package is enabled by dotnet pack as discussed https://github.com/dotnet/docs/blob/main/docs/core/tools/global-tools-how-to-create.md. I have update the doc to link the instructions

learn-build-service-prod · 2025-01-16T00:27:23Z

Learn Build status updates of commit 2ceb6cf:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md	💡Suggestion	View	Details

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

Line 116, Column 80: [Suggestion: learn-site-link-broken - See documentation] Link '/dotnet/core/tools/global-tools-how-to-create.md' points to a learn site page that doesn't exist. Check the path or URL and update the link.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

Try searching the learn.microsoft.com contributor guides
Post your question in the Learn support channel

nkolev92

This doc is authored more as a conceptual doc, but the tone of the changes feels like more of a pitch.

I think the language should be tweaked to be more "matter of fact" way.

nkolev92 · 2025-01-16T18:11:41Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+- `NUGET_PLUGIN_PATHS`
+  - defines the plugins that will be used for that NuGet process, priority preserved. If this environment variable is set, it overrides the convention based discovery. Ignored if either of the framework specific variables is specified.
+
+  - Starting 6.13, this can also be used to specify a path to a .Net tools plugin path.


Suggested change

- Starting 6.13, this can also be used to specify a path to a .Net tools plugin path.

- Starting 6.13, this can also be used to specify a path to a .NET tools plugin path.

- ```

nkolev92 · 2025-01-16T18:16:41Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+1. Plugins installed as .NET tools must follow a naming convention: **`nuget-plugin-*`**.
+2. Upon installation, these plugins are added to the `PATH` by the .NET SDK. NuGet scans the `PATH` environment variable for executables with names starting with `nuget-plugin-`.
+3. In addition to number 1, on Windows, NuGet looks for `.exe` or `.bat` files, while on Linux and macOS, it identifies plugins by checking for the executable bit.
+4. These plugins are launched in a separate process, consistent with the existing design.


I think this type of information made sense in the design, but this document is talking about all plugins period, so I think we can remove it.

nkolev92 · 2025-01-16T18:19:00Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+
+1. Plugins installed as .NET tools must follow a naming convention: **`nuget-plugin-*`**.
+2. Upon installation, these plugins are added to the `PATH` by the .NET SDK. NuGet scans the `PATH` environment variable for executables with names starting with `nuget-plugin-`.
+3. In addition to number 1, on Windows, NuGet looks for `.exe` or `.bat` files, while on Linux and macOS, it identifies plugins by checking for the executable bit.


I think these are in a way separate features.

The support is that nuget-plugin-* is looked from the path, the fact that .NET tools are how it's going to be done is a separate.

This document serves as more of a reference, telling you how things work.

nkolev92 · 2025-01-16T18:19:58Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+
+#### Example Workflow
+
+**For Plugin Authors:**


nit: I think is too much detail.
Say it can be installed as a .NET tool by linking and it's enough.

It doesn't need to be a step by step guide.

nkolev92 · 2025-01-16T18:20:43Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+    ```xml
+    <PropertyGroup>
+      <PackAsTool>true</PackAsTool>
+      <ToolCommandName>nuget-plugin-myplugin</ToolCommandName>


My suggestion would be remove this, but package name and tool command name aren't necessarily the same.

nkolev92 · 2025-01-16T18:21:04Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+
+### Security Considerations
+
+.NET tools run in full trust. It is essential to install only trusted plugins. While this is not a new concern, users should be aware of the risks when installing NuGet plugins via .NET tools.


Doesn't this apply to plugins in general?
Should this be a generic statement?

nkolev92 · 2025-01-16T18:22:36Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

+    dotnet tool install -g nuget-plugin-myplugin
+    ```
+
+2. Use the plugin seamlessly in scenarios requiring NuGet authentication or operations like `dotnet restore --interactive`.


I think we should remove this is. People would normally expect that the tools regardless of how they're installed would work the same.

learn-build-service-prod · 2025-01-27T23:40:18Z

Learn Build status updates of commit 5457a9f:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

Try searching the learn.microsoft.com contributor guides
Post your question in the Learn support channel

learn-build-service-prod · 2025-01-27T23:41:22Z

Learn Build status updates of commit 35dae67:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

Try searching the learn.microsoft.com contributor guides
Post your question in the Learn support channel

Nigusu-Allehu · 2025-01-27T23:42:06Z

This doc is authored more as a conceptual doc, but the tone of the changes feels like more of a pitch. I think the language should be tweaked to be more "matter of fact" way.

That makes sense as my documentation was motivated by the design spec. I have simplified it to mention things that would concern users only.

nkolev92 · 2025-01-31T18:28:01Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

@@ -47,11 +47,14 @@ Under this version, the requirements are as follows:
 - Adhere to the negotiated plugin protocol version.
 - Respond to all requests within a reasonable time period.
 - Honor cancellation requests for any in-progress operation.
+- Plugins installed as global .NET tools starting with NuGet 6.13. These plugins:


Should we mention that the feature is more about executables on the path?

nkolev92 · 2025-01-31T18:29:18Z

docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md

@@ -70,7 +73,10 @@ CI/CD scenarios and power users can use environment variables to override the be

 - `NUGET_NETFX_PLUGIN_PATHS` - defines the plugins that will be used by the .NET Framework based tooling (NuGet.exe/MSBuild.exe/Visual Studio). Takes precedence over `NUGET_PLUGIN_PATHS`. (NuGet version 5.3+ only)
 - `NUGET_NETCORE_PLUGIN_PATHS` - defines the plugins that will be used by the .NET Core based tooling (dotnet.exe). Takes precedence over `NUGET_PLUGIN_PATHS`. (NuGet version 5.3+ only)
- `NUGET_PLUGIN_PATHS` - defines the plugins that will be used for that NuGet process, priority preserved. If this environment variable is set, it overrides the convention based discovery. Ignored if either of the framework specific variables is specified.
+- `NUGET_PLUGIN_PATHS`


This comment is about the Plugin installation and discovery section.

We should call ouit that search for nuget-plugin-* executables here as well. We only have it in the general plugin requirements right now.

Document dotnet tools plugin usage

18ce1c9

Nigusu-Allehu requested review from a team as code owners December 6, 2024 00:21

env variable

eba36da

Nigusu-Allehu self-assigned this Dec 6, 2024

Update NuGet-Cross-Platform-Plugins.md

7de8612

nkolev92 reviewed Dec 6, 2024

View reviewed changes

Comments

2ceb6cf

Nigusu-Allehu requested review from nkolev92, jebriede and jeffkl January 16, 2025 00:26

nkolev92 reviewed Jan 16, 2025

View reviewed changes

Nigusu-Allehu added 2 commits January 27, 2025 15:38

Simplify

5457a9f

Simplify

35dae67

Nigusu-Allehu requested a review from nkolev92 January 27, 2025 23:42

nkolev92 reviewed Jan 31, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document dotnet tools plugin usage #3379

Document dotnet tools plugin usage #3379

Nigusu-Allehu commented Dec 6, 2024

learn-build-service-prod bot commented Dec 6, 2024

learn-build-service-prod bot commented Dec 6, 2024

learn-build-service-prod bot commented Dec 6, 2024

nkolev92 Dec 6, 2024

Nigusu-Allehu Jan 16, 2025 •

edited

Loading

learn-build-service-prod bot commented Jan 16, 2025

nkolev92 left a comment

nkolev92 Jan 16, 2025

nkolev92 Jan 16, 2025

nkolev92 Jan 16, 2025

nkolev92 Jan 16, 2025

nkolev92 Jan 16, 2025

nkolev92 Jan 16, 2025

nkolev92 Jan 16, 2025

learn-build-service-prod bot commented Jan 27, 2025

learn-build-service-prod bot commented Jan 27, 2025

Nigusu-Allehu commented Jan 27, 2025

nkolev92 Jan 31, 2025

nkolev92 Jan 31, 2025

	- Starting 6.13, this can also be used to specify a path to a .Net tools plugin path.
	- Starting 6.13, this can also be used to specify a path to a .NET tools plugin path.
	- ```


		### Security Considerations

		.NET tools run in full trust. It is essential to install only trusted plugins. While this is not a new concern, users should be aware of the risks when installing NuGet plugins via .NET tools.

Document dotnet tools plugin usage #3379

Are you sure you want to change the base?

Document dotnet tools plugin usage #3379

Conversation

Nigusu-Allehu commented Dec 6, 2024

learn-build-service-prod bot commented Dec 6, 2024

✅ Validation status: passed

learn-build-service-prod bot commented Dec 6, 2024

✅ Validation status: passed

learn-build-service-prod bot commented Dec 6, 2024

✅ Validation status: passed

Choose a reason for hiding this comment

Nigusu-Allehu Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

learn-build-service-prod bot commented Jan 16, 2025

💡 Validation status: suggestions

nkolev92 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

learn-build-service-prod bot commented Jan 27, 2025

✅ Validation status: passed

learn-build-service-prod bot commented Jan 27, 2025

✅ Validation status: passed

Nigusu-Allehu commented Jan 27, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Nigusu-Allehu Jan 16, 2025 •

edited

Loading