The sample project references local files, how is meant to be used in stand alone extensions?

[Yazwh0]

Is your feature request related to a problem? Please describe.

The sample app doesn't work in the realworld. For example, what is the package name that we're supposed to install to be able to import? (so import * as runtimeExtension from '@microsoft/vscode-dotnet-runtime'; doesn't error.)

From the comments we're meant to reference the external extension, but how does this string together. npm search vscode-dotnet-runtime returns nothing,.

Are we supposed to include the source into our extensions?

A clear and concise description of what you want to happen. Include any alternative solutions you've considered.

A better sample application, which can run without referencing the source in the repository.

Describe the solution you'd like

A proper, stand alone example using released libraries of how this is supposed to work.

Additional context

No response

[nagilson]

There is no managed npm library that we provide for other extensions (technically the library folder could become one but there are no plans for that.) We provide commands for other extensions to call through the VS Code Command API. The Sample Extension code shows how to call those APIs and what APIs are available.

E.g.

To install a global .NET SDK, your extension would need to take a dependency on our extension (which VS Code would automatically install if its a dependency.) Then you could call our API in code like so: (this is ripped from the sample extension.)

            let commandContext : IDotnetAcquireContext = { version, requestingExtensionId, installType: 'global' };
            await vscode.commands.executeCommand('dotnet.acquireGlobalSDK', commandContext);

Technically there isnt anything to import, you dont need that acquire context type. https://github.com/dotnet/vscode-csharp uses it and is a good example.

[Yazwh0]

But where does IDotnetAcquireContext get referenced from? You dont get any dependencies from adding things to extensionDependancies.

So you have to reference the source in the vscode-dotnet-runtime extension directly if you want to use the example above?

[nagilson]

No, you don't have to reference it. The interface / type should not be necessary, you could just pass it an object that matches the type. This is a core quirk of typescript, where if it has the right properties any object can be used as a different type. Of course its better to use types when you can, but the vscode API does not provide type safety checks anyways, so it would mostly be for code style.

Like

  await vscode.commands.executeCommand('dotnet.acquireGlobalSDK',  { version: '7.0.103', requestingExtensionId: 'my.extension.id', installType: 'global' });

Now that you point it out though, yeah, I do agree it is a poor design. When I onboarded onto the project I also found it confusing.

As for what internal teams do, like the C# extension, they dont have the IDotnetAcquireContext type. But they did make a clone interface for our API return type. https://github.com/dotnet/vscode-csharp/blob/e9f0a1376d7ad7ddad7acf762a897784aa48f80a/src/lsptoolshost/dotnetRuntimeExtensionResolver.ts#L21

Here is an example of them calling our API, as you can see it is not necessary to import the type from our library: https://github.com/dotnet/vscode-csharp/blob/e9f0a1376d7ad7ddad7acf762a897784aa48f80a/src/lsptoolshost/dotnetRuntimeExtensionResolver.ts#L105

Anyway I do agree thats pretty meh. Its very possible this was designed to be shipped as a library but it never happened. The extension page never really made it clear what the extension even was for until we fixed it recently, so I'm not sure the intention of the initial design was for it to be used outside of internal teams, though I am happy to see people get use out of it. Somehow along the way it did pick up external users such as the CMake extension and we do definitely take a look at issues from external users too and try to support them.

@baronfel may be able to add more.