You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We are getting ready to finalize the ports attributes API. This API was added to allow extension that run processes to provide an "action" to take when VS Code notices their port for auto forwarding.
Here's are a few examples of how a ports attributes provider could work:
Opening the preview browser
When connected to a remote, the extension starts a process at localhost:3000 (on the remote). When this process starts, the extension wants to open the preview browser to https://localhost:3000. This extension could use a ports attributes provider to cause the preview browser to open ever time port 3000 is auto forwarded.
Extension internals
The extension always starts a server that listens on a random port between 5050 and 5100, which is used only for internal extension communication. When running locally, the user never knows about the server (unless they're watching their task manager or other list of running processes). When running in a remote, this port always gets auto forwarded, which not only forwards the port so it shows in the Ports view, but also disrupts the user with a notification. This extension could use a ports attributes provider to cause it's ports to be ignored entirely from auto forwarding.
Pointers
I tried to assign testers who work on extensions that could benefit from having a ports attributes provider. If you have any questions, please let me know!
* If your extension listens on ports, consider registering a PortAttributesProvider to provide information
* about the ports. For example, a debug extension may know about debug ports in it's debuggee. By providing
* this information with a PortAttributesProvider the extension can tell the editor that these ports should be
* ignored, since they don't need to be user facing.
*
* The results of the PortAttributesProvider are merged with the user setting `remote.portsAttributes`. If the values conflict, the user setting takes precedence.
*
* @param portSelector It is best practice to specify a port selector to avoid unnecessary calls to your provider.
* If you don't specify a port selector your provider will be called for every port, which will result in slower port forwarding for the user.
* @param provider The {@link PortAttributesProvider PortAttributesProvider}.
* A selector that will be used to filter which {@link PortAttributesProvider} should be called for each port.
*/
exportinterfacePortAttributesSelector{
/**
* Specifying a port range will cause your provider to only be called for ports within the range.
*/
portRange?: [number,number];
/**
* Specifying a command pattern will cause your provider to only be called for processes whose command line matches the pattern.
*/
commandPattern?: RegExp;
}
Things to verify
After you have implemented your provider, run your extension when connected to a remote. On the remote, run a process that listens on a port and verify the following:
Verify that your provider only gets called for ports that match your selector.
Verify that the action you provide is respected. Try some other actions and verify that they all work as expected.
Set the remote.portsAttributes setting with a value that conflicts with what your provider returns. Verify that the setting wins.
Verify that the JS doc comments make sense.
If you can't use a selector, please comment with why.
The text was updated successfully, but these errors were encountered:
Had some issues trying to test this in Codespaces so I really didn't get started. Feel free to steal from me or I'll do it first thing tomorrow morning.
@TylerLeonhardt thanks for trying to test this! Given that this is proposed API and I think @paulacamargo25 will be testing the API anyway for the Python extension at some point in the next couple weeks, I'm ok with you leaving this for @paulacamargo25 for later. If you do want to test it then that is also great!
Refs: #115616
Complexity: 5
Create Issue
Background
We are getting ready to finalize the ports attributes API. This API was added to allow extension that run processes to provide an "action" to take when VS Code notices their port for auto forwarding.
Here's are a few examples of how a ports attributes provider could work:
Opening the preview browser
When connected to a remote, the extension starts a process at localhost:3000 (on the remote). When this process starts, the extension wants to open the preview browser to https://localhost:3000. This extension could use a ports attributes provider to cause the preview browser to open ever time port 3000 is auto forwarded.
Extension internals
The extension always starts a server that listens on a random port between 5050 and 5100, which is used only for internal extension communication. When running locally, the user never knows about the server (unless they're watching their task manager or other list of running processes). When running in a remote, this port always gets auto forwarded, which not only forwards the port so it shows in the Ports view, but also disrupts the user with a notification. This extension could use a ports attributes provider to cause it's ports to be ignored entirely from auto forwarding.
Pointers
I tried to assign testers who work on extensions that could benefit from having a ports attributes provider. If you have any questions, please let me know!
You'll need to register a provider:
vscode/src/vscode-dts/vscode.proposed.portsAttributes.d.ts
Lines 89 to 101 in 0524ecc
And specify a selector in the provider:
vscode/src/vscode-dts/vscode.proposed.portsAttributes.d.ts
Lines 73 to 86 in 0524ecc
Things to verify
After you have implemented your provider, run your extension when connected to a remote. On the remote, run a process that listens on a port and verify the following:
remote.portsAttributes
setting with a value that conflicts with what your provider returns. Verify that the setting wins.The text was updated successfully, but these errors were encountered: