Extension Development: How do I update my extension project with new releases of ADS?

[dfalso]

I've created a Typescript extension project (using yo). How do I update my project when new versions of Azure Data Studio come out?

For instance, I see that my extension folder has the .\node_modules@types\azdata\index.d.ts file locally. If a new release of ADS has a new version of this file, does it get updated? What about if a new version has changes to package.json (say, new devDependencies item versions)?
If not, is there a best practice for updating?

[Charles-Gagnon]

We release a new version of the typings every time we release - see https://www.npmjs.com/package/@types/azdata. Note that these are just typings - they have no impact on the runtime of the extension. So it's good practice to update that version every time we release a new one but is not strictly necessary.

I'm not sure I understand the second part - you'll be creating the VSIX which involves bundling in all the dependencies needed for your extension at build time. So every time you release a new version of the extension these may or may not be updated based on whether you've updated the dependencies in your package.json. ADS being updated has nothing to do with your package dependencies - the only thing that could change is the APIs available to your extension (but those should never have breaking changes made so you can expect them to work the same version-to-version)

[dfalso]

Thanks for responding.
This certainly could be me not being familiar with this development environment, so I'll try to give some examples:

I'm using VS Code to develop a Typescript extension, in Windows. When I right-click an ADS object reference in my code (say, azdata.SimpleExecuteResult) and Go To Definition, it takes me to the index.d.ts file in C:\Users\<me>\source\repos\<my extension>\node_modules\@types\azdata\. I'm assuming that this is what VS Code uses as a reference when transpiling. My question was surrounding files like these - I'm assuming my local index.d.ts doesn't get updated unless I manually do so, correct? In the case of #19509, my index.d.ts would continue to show the old description for connect(), wouldn't it?
Similarly, if the current version of "vscode" key " in "engines" were ^1.39.0", but my project was started earlier and against "^1.35.0" (making up a version here), I'd have to edit my package.json and update that value manually, correct?

Does this help?

[Charles-Gagnon]

Yes, it will continue to show the old version of the function and that isn't likely to change until the next stable release sometime next month.

You are correct, that index.d.ts file is what the TS compiler pulls in during build (and VS Code uses during development through the Typescript server support).

The engines field is only somewhat related to the typings file. The version there is telling VS Code (or ADS in our case) what versions your extension supports. So putting ^1.35.0 there means that your extension will work against all versions 1.35.0+. You typically don't ever need to update this value unless you add new functionality that depends on new APIs added in a newer version of ADS/VS Code.

The typings files should generally match that version (because that's the min version of the API that you say you support), but it doesn't have to. You can update the typings to be newer if you want and as long as you're not using any new functionality added. But given that that can be hard to tell for sure it's probably safest to keep the typings file in line with the engine version.

The VS Code Docs are a good place to go for general information about how all this works too, they might do a better job of explaining all this and generally are pretty accurate even for ADS (although there may be a few things that they've changed which we haven't brought over yet)

Hopefully that all makes sense - to break it down into a few bullet points :

• Typically when a new version of ADS comes out you don't need to do anything, your function will continue to work as it has
• You can continue to make changes to your extension and publish new versions without updating the engine version as long as you don't need to use any new functionality introduced in later versions of ADS (stuff like updating comments doesn't really fall into this since those don't have any functional changes)
• If you do need to use a new API or newer version of the API then you should generally updating both the engine version and typings version to match the version of the API that supports the new functionality you need

[dfalso]

OK, I think I see:
Since my value for devDependencies @types/azdata key is "*", Visual Studio Code will automatically look for the most current package through npm, and next month will find 1.36 and download it. Correct?
I was worried that I would have to run npm manually for my projects and put the index files in each one.

[Charles-Gagnon]

It's not VS Code that does that but rather npm/yarn when you install the packages (which get put under the node_modules folder). VS Code just loads the files from that folder.

So if we release a new version of @types/azdata and then you re-run npm install or yarn install then you should see the updated index.d.ts being used by VS Code. But until you do that you'll continue to use whatever version of the package you had before (unless something else is doing that for you in the background, but that's not very typical)

But yes, that means that you'll need to run npm/yarn for each project you're working on - this is a standard part of any JS/TS project in order to pull down dependencies. But typically it's something you won't need to do very often - mostly just as an initial setup for a new enlistment (or when you modify the packages)

[dfalso]

Sorry for not responding earlier, I was on other projects for a bit.
I was specifically thinking about additions to the ADS engine - for instance, if a new method were added I wanted to take advantage of in my project, I'd want to update the types.
I ended up testing this since the new version was released, by going in the Terminal of VS Code (with my project open) and running:
npm install --save @types/azdata
and checked the azdata.connection.connect method, and got the updated typing information you added. So I'm marking this as answered. Thanks for all your help!

[dfalso]

(I really wanted to mark your reply as the answer, but it doesn't allow me to do that, so I'm marking this discussion block as the answer)

[Charles-Gagnon]

Glad to hear!

And then down the road it's a good idea to be pulling in the latest version of the typings periodically so you always have the latest. Although staying on this version shouldn't be a problem - backwards compat is a huge deal to us so typically we won't do anything that would break compilation for existing projects if you update. It's more of keeping up to date with the latest fixes to comments and new functionality that you might find useful.