Example – Hello World – Your first extension

Original URL…

Extending Visual Studio Code

Your first extension

This document will guide you through creating your first VS Code extension (“Hello World”) and explain the basic VS Code extensibility concepts.

In this walkthrough, you’ll add a new command to VS Code which will display a simple “Hello World” message. Later in the walkthrough, you’ll interact with the VS Code editor and query for the user’s currently selected text.

Prerequisites

You need Node.js installed and available in your $PATH. Node.js includes npm, the Node.js Package Manager, which will be used to install the extension generator.

Generate a new extension

The simplest way to add your own functionality to VS Code is through adding a command. A command registers a callback function which can be invoked from the Command Palette or with a key binding.

We have written a Yeoman generator to help get you started. Install Yeoman and the Yeoman VS Code Extension generator and scaffold a new extension:

npm install -g yo generator-code
yo code

For the hello world extension, you can either create a TypeScript extension or a JavaScript one. For this example, we pick a TypeScript extension.

The command generator

Running your extension

  • Launch VS Code, choose File > Open Folder and pick the folder that you generated.
  • Press F5 or click on the Debug icon and click Start.
  • A new instance of VS Code will start in a special mode (Extension Development Host) and this new instance is now aware of your extension.
  • Press Ctrl+Shift+P and run the command named Hello World.
  • Congratulations! You’ve just created and executed your first VS Code command!

Running VS Code with an extension

The structure of an extension

After running, the generated extension should have the following structure:

.
├── .gitignore
├── .vscode                     // VS Code integration
│   ├── launch.json
│   ├── settings.json
│   └── tasks.json
├── .vscodeignore               // files ignored when publishing extension
├── README.md
├── src
│   └── extension.ts            // the source of the extension entry point
├── test                        // test folder
│   ├── extension.test.ts       // extension.test.js, in case of JavaScript extension
│   └── index.ts                // index.js, in case of JavaScript extension
├── node_modules
│   ├── vscode                  // include vscode type definition file 
for extension development
│   └── typescript              // compiler for typescript (TypeScript only)
├── out                         // compilation output (TypeScript only)
│   ├── extension.js            // the extension entry point
│   ├── extension.js.map
│   └── test
│       ├── extension.test.js
│       ├── extension.test.js.map
│       ├── index.js
│       └── index.js.map
├── package.json                // extension's manifest
├── tsconfig.json               // jsconfig.json, in case of JavaScript extension
└── vsc-extension-quickstart.md // extension development quick start

Let’s go through the purpose of all these files and explain what they do:

The extension manifest: package.json

Example TypeScript extension manifest

{
    "name": "myFirstExtension",
    "description": "",
    "version": "0.0.1",
    "publisher": "",
    "engines": {
        "vscode": "^1.5.0"
    },
    "categories": [
        "Other"
    ],
    "activationEvents": [
        "onCommand:extension.sayHello"
    ],
    "main": "./out/extension",
    "contributes": {
        "commands": [{
            "command": "extension.sayHello",
            "title": "Hello World"
        }]
    },
    "scripts": {
        "vscode:prepublish": "tsc -p ./",
        "compile": "tsc -watch -p ./",
        "postinstall": "node ./node_modules/vscode/bin/install",
        "test": "node ./node_modules/vscode/bin/test"
    },
    "devDependencies": {
       "typescript": "^2.0.3",
        "vscode": "^1.5.0",
        "mocha": "^2.3.3",
        "@types/node": "^6.0.40",
        "@types/mocha": "^2.2.32"
   }
}

Note: A JavaScript extension doesn’t require the scripts field as no compilation is needed.

This specific package.json describes an extension that:

  • contributes an entry to the Command Palette (Ctrl+Shift+P) with the label "Hello world" that will invoke a command "extension.sayHello".
  • requests to get loaded (activationEvents) when the command "extension.sayHello" is invoked.
  • has its main JavaScript code in a file called "./out/extension.js".

Note: VS Code does not load the code of an extension eagerly at start-up. An extension must describe, through the activationEvents property under what conditions it should get activated (loaded).

Generated code

The generated extension’s code is in extension.ts (or extension.js in case of a JavaScript extension):

// The module 'vscode' contains the VS Code extensibility API
// Import the module and reference it with the alias vscode in your code below
import * as vscode from 'vscode';

// this method is called when your extension is activated
// your extension is activated the very first time the command is executed
export function activate(context: vscode.ExtensionContext) {

    // Use the console to output diagnostic information (console.log) and 
errors (console.error)
    // This line of code will only be executed once when your extension is activated
    console.log('Congratulations, your extension "my-first-extension" is now 
active!');

    // The command has been defined in the package.json file
    // Now provide the implementation of the command with  registerCommand
    // The commandId parameter must match the command field in package.json
    let disposable = vscode.commands.registerCommand('extension.sayHello', () => {
        // The code you place here will be executed every time your 
command is executed

        // Display a message box to the user
        vscode.window.showInformationMessage('Hello World!');
    });

    context.subscriptions.push(disposable);
}
  • Each extension should export from its main file a function named activate(), which VS Code will invoke only once when any of the activationEvents described in the package.json file occur.
  • If an extension makes use of OS resources (e.g. spawns processes), the extension can export from its main file a function named deactivate() where it can do clean-up work and VS Code will invoke that function on shutdown.
  • This specific extension imports the vscode API and then registers a command, associating a function to be called when the command "extension.sayHello" gets invoked. The command’s implementation displays a “Hello world” message in VS Code.

Note: The contributes section of the package.json adds an entry to the Command Palette. The code in extension.ts/.js defines the implementation of "extension.sayHello".

Note: For TypeScript extensions, the generated file out/extension.js will be loaded at runtime and executed by VS Code.

Miscellaneous files

  • .vscode/launch.json defines launching VS Code in the Extension Development mode. It also points with preLaunchTask to a task defined in .vscode/tasks.json that runs the TypeScript compiler.
  • .vscode/settings.json by default excludes the out folder. You can modify which file types you want to hide.
  • .gitignore – Tells Git version control which patterns to ignore.
  • .vscodeignore – Tells the packaging tool which files to ignore when publishing the extension.
  • README.md – README file describing your extension for VS Code users.
  • vsc-extension-quickstart.md – A Quick Start guide for you.
  • test/extension.test.ts – you can put your extension unit tests in here and run your tests against the VS Code API (see Testing Your Extension)

Extension activation

Now that the roles of the files included in the extension are clarified, here is how your extension gets activated:

  • The extension development instance discovers the extension and reads its package.json file.
  • Later when you press Ctrl+Shift+P:
  • The registered commands are displayed in the Command Palette.
  • In this list there is now an entry "Hello world" that is defined in the package.json.
  • When selecting the "Hello world" command:
  • The command "extension.sayHello" is invoked:
    • An activation event "onCommand:extension.sayHello" is created.
    • All extensions listing this activation event in their activationEvents are activated.
      • The file at ./out/extension.js gets loaded in the JavaScript VM.
      • VS Code looks for an exported function activate and calls it.
      • The command "extension.sayHello" is registered and its implementation is now defined.
  • The command "extension.sayHello" implementation function is invoked.
  • The command implementation displays the “Hello World” message.

Debugging your extension

Set a breakpoint, for example inside the registered command, and run the "Hello world" command in the Extension Development VS Code instance.

Debugging the extension

Note: For TypeScript extensions, even though VS Code loads and executes out/extension.js, you are actually able to debug the original TypeScript code due to the generated source map out/extension.js.map and VS Code’s debugger support for source maps.

Tip: The Debug Console will show all the messages you log to the console.

To learn more about the extension development environment.

A simple change

In extension.ts (or extension.js, in a JavaScript extension), try replacing the extension.sayHello command implementation to show the number of characters selected in the editor:

    let disposable = vscode.commands.registerCommand('extension.sayHello', () => {
        // The code you place here will be executed every time your 
command is executed

        let editor = vscode.window.activeTextEditor;
        if (!editor) {
            return; // No open text editor
        }

        let selection = editor.selection;
        let text = editor.document.getText(selection);

        // Display a message box to the user
        vscode.window.showInformationMessage('Selected characters: ' + text.length);
    });

Tip: Once you make changes to the extension source code, you need to restart the Extension Development Host instance of VS Code. You can do that by using Ctrl+R (macOS: Cmd+R) in the Extension Development Host instance or by clicking the Restart button at the top of your primary VS Code instance.

Create a file (File > New File), type some text and select it. When you run the Hello World command, you should now see the count of selected characters.

Running the modified extension

Installing your extension locally

So far, the extension you have written only runs in a special instance of VS Code, the Extension Development instance. To get your extension running in all instances of VS Code, you need to copy it to a new folder under your local extensions folder:

  • Windows: %USERPROFILE%\.vscode\extensions
  • macOS/Linux: $HOME/.vscode/extensions

Publishing your extension

Read about how to Share an Extension.

Next Steps

In this walkthrough, we’ve seen a very simple extension. For a more detailed example, see the Word Count Example which shows how to target a specific language (Markdown) and listen to the editor’s document changed events.

If you’d like to read more generally about the extension APIs, try these topics:

Anuncios

How to get the new Dynamics 365 Business Central and extend it

Original URL…

What is it?

Dynamics 365 Business Central is the new and, I hope, the last official name of Dynamics NAV.

No more Dynamics 365 Finance and operations Business Edition, no more Dynamics 365 “Tenerife”, even no more Dynamics NAV (basically it is yes now, until Q4 2018, when D365BC on-premise will be released)!

The official announcement was made 4 days ago and can be found here.

2 days after at DirectionsASIA we’ve got much more information about the product from Microsoft team.

The official hashtag is #MSDyn365BC, and if you will search it on twitter you will find a huge portion of images and info about new web client, new roadmap, new possibilities and so on.

But this blog is not about What’s new staff. It is about How to get it?

Step 1. Register on collaborate portal

If you are already registered – skip it. If not, go to https://aka.ms/collaborate and register.

The registration process is very nice described here https://docs.microsoft.com/en-us/collaborate/registration

Just go steps by steps, and you should be able to see this

 

Step 2. Register on Ready to Go program (Updated)

After publishing first version of this blog, I’ve got many questions about why D365BC is not visible on collaboration portal. Because of this step was missed. Sorry. Updated.

If you are already registered – skip it. If not you should sign up for Ready to Go program http://aka.ms/ReadyToGo

To do so, after step 1, please write an e-mail to Dyn365BEP@microsoft.com

When contacting, please provide following information:

Publisher display name Name Email Role
Chosen during registration, should be the same for all users User 1 Email 1 Power user (can access content and add new users to engagements)
User 2 Email 2 Participant (can access content)
Etc. Etc. Power user

The registration process should take 1-2 business days.

After successful registration, you will be able to see this

 

YES! This is pre-release version of NEW Dynamics 365 Business Central.

If you click on it you will find something interesting, guess what?

.Zip, DVD?  No =)

You will find 2kb txt file with instructions of …. How to get it via Docker.

Download it.

Advantages of Ready to Go program

Ready to Go program, it is not only the possibility to download and play with pre-release versions of Dynamics 365 Business Central.

The idea is to prepare every partner for new SaaS world. It consists of training materials on http://aka.ms/ReadyToGoOnlineLearning and also potentially coaching through a Development Centres

BTW. If you want to prepare yourself for new modern SaaS world, you can also contact me for individual workshops and coaching.

Step 3. Create new Docker container with Dynamics 365 Business Central

But first, Install Docker.

If you don’t have docker, then download and install it. You can choose to download a full docker client or only a module.

You can download and install docker as a module executing this code in PowerShell

invoke-webrequest -UseBasicparsing -Outfile docker-17.09.0-ce.zip 
https://download.docker.com/win/static/stable/x86_64/docker-17.09.0-ce.zip
# Extract the archive.
Expand-Archive docker-17.09.0-ce.zip -DestinationPath $Env:ProgramFiles

# Clean up the zip file.
Remove-Item -Force docker-17.09.0-ce.zip

# Install Docker. This requires rebooting.
$null = Install-WindowsFeature containers

# Add Docker to the path for the current session.
$env:path += ";$env:ProgramFiles\docker"

# Optionally, modify PATH to persist across sessions.
$newPath = "$env:ProgramFiles\docker;" +
[Environment]::GetEnvironmentVariable("PATH",
[EnvironmentVariableTarget]::Machine)

[Environment]::SetEnvironmentVariable("PATH", $newPath,
[EnvironmentVariableTarget]::Machine)

# Register the Docker daemon as a service.
dockerd --register-service

# Start the Docker service.
Start-Service docker

#Next steps are optional!

#Run test container, to check that Docker is alive
docker container run hello-world:nanoserver

# Check what containers do you have
docker ps

Next, install Navcontainerhelper

I personally love what Freddy has done to us. So I will use navcontainerhelper to simplify my work.

Run next script in PowerShell

Install-Module -Name navcontainerhelper -Verbose

If, you are running it on Windows10, check that your policy is allowed you to install new modules.

If it is restricted, then change it

Create new D365 Business Central container

1)    Login to azure container register, to be able to pull (download) D365BE Image (also in powershell).

docker login "navinsider.azurecr.io" -u 
"insert-user-id-here-from-Build-21063.txt-file" -p " 
insert-password-here-from-Build-21063.txt-file "

2)    Choose what version of Business Central do you want.

Currently available 14 Versions and W1!

dynamics-nav:11.0.21063.0

dynamics-nav:11.0.21063.0-finat

dynamics-nav:11.0.21063.0-finbe

dynamics-nav:11.0.21063.0-finca

dynamics-nav:11.0.21063.0-finch

dynamics-nav:11.0.21063.0-finde

dynamics-nav:11.0.21063.0-findk

dynamics-nav:11.0.21063.0-fines

dynamics-nav:11.0.21063.0-finfi

dynamics-nav:11.0.21063.0-finfr

dynamics-nav:11.0.21063.0-fingb

dynamics-nav:11.0.21063.0-finit

dynamics-nav:11.0.21063.0-finnl

dynamics-nav:11.0.21063.0-finse

dynamics-nav:11.0.21063.0-finus

3)    Create new container

I will use W1 version, so I run next command in PowerShell

New-NavContainer -accept_eula -alwaysPull -imageName 
"navinsider.azurecr.io/dynamics-nav:11.0.21063.0" -containerName D365BC-W1

and after a while – about 5 minutes of pulling (depends on your internet speed), and 2 minutes of initialization – we have it!

This wonderful, modern look and feel web UI

Hmm…. Not really what I was expected =)

Let’s try old trick =) We will add ?aid=fin to the end of our URL.

So url will be http://d365bc-w1/nav/?aid=fin

 

Much better now!

By the way, if you will create a container from US image (dynamics-nav:11.0.21063.0-finus), then we will have new web UI by default.

 

Step 4. Extend it!

Install Visual Studio Code AL extension

First copy .vsix file on your host.

To do so, copy a link to vsix file from container creation log

Open it in a browser

Click Save.

Open Visual Studio Code. Go to Extentions -> … -> Install From Vsix

Create new AL project

As usual, press Crtl + Shift + P -> AL:Go

We change server in launch.json (take it from container creation log), and authentication to Windows.

Press Crtl + Shift + P -> AL:Download Symbols

Then we will create some new code.

We will add one more insight to RoleCenter. This is really wow feature of new UI.

After publishing (ctrl+F5) we will see new insight!

And we’ve done!

I encourage you to take all advantages of Collaborate and start exploring Dynamics 365 Business Central right now!

Publishing and Installing an Extension v2.0

Original URL…

  1. Publish and synchronize an extensión
  2. Install an extension
  3. See Also

The AL developer environment is evolving with frequent updates. To stay up to date on the latest information and announcements, follow us on the Dynamics NAV Team Blog.

To make your extension available to tenant users requires three basic tasks: publish the extension package to the Dynamics 365 Business Central server instance, synchronize the extension with the tenant database, and install the extension on the tenant.

Note

This article describes how to publish and install the first version of a V2 extension. If you want to publish an install newer version of an extension, see Upgrading Extensions V2.

Publish and synchronize an extension

Publishing an extension to a Dynamics 365 Business Central server instance adds the extension to the application database that is mounted on the server instance, making it available for installation on tenants of the server instance. Publishing updates internal tables, compiles the components of the extension behind-the-scenes, and builds the necessary metadata objects that are used at runtime.

Synchronizing an extension updates the database schema of the tenant database with the database schema that is defined by the extension objects. For example, if a table or table extension is included in the extension, then the respective full or companion table is created in the tenant database.

To publish and synchronize an extension

  1. Start the Microsoft Dynamics NAV Administration Shell.
  2. To publish the extension, run the Publish-NAVApp cmdlet.The cmdlet takes as parameters the Dynamics 365 Business Central service instance that you want to install to and the .app package file that contains the extension. The following example publishes the extension MyExtension.app to the YourDynamicsNAVServer instance.
  • Publish-NAVApp -ServerInstance YourDynamicsNAVServer -Path ".\MyExtension.app"
    
  • To synchronize the schema of a tenant database to the extension, run the Sync-NavApp cmdlet.The following example synchronizes the extension MyExtension with the tenant:

 

  1. Sync-NavApp -ServerInstance YourDynamicsNAVServer -Name ExtensionName 
    -Path “.\MyExtension.app” -Tenant TenantID
    

    Replace TenantID with the tenant ID of the database. If you do not have a multitenant server instance, use default or omit this parameter.

The extension can now be installed on tenants.

Install an extension

After you publish and synchronize an extension, you can install it on tenants to enable the extension and make it available to users in the client. Installing an extension can be done from the Dynamics 365 client or Microsoft Dynamics NAV Administration Shell.

Note

Installing an extension will run any installation code that is built-in to the extension. Installation code could, for example, perform operations like populating empty records with data, service callbacks and telemetry, version checks, and messages to users. For more information, see Writing Extension Install Code.

To install an extension by using Microsoft Dynamics NAV Administration Shell

  1. Start the Microsoft Dynamics NAV Administration Shell.
  2. To install the extension on one or more tenants, use the Install-NAVApp cmdlet.The following example installs the extension My Extension for Tenant1 and Tenant3. In single-tenant deployments, you either specify default as the tenant ID, or you omit the –Tenant parameter.
  1. Install-NAVApp -ServerInstance YourDynamicsNAVServer -Name 
    ”My Extension” –Tenant Tenant1, Tenant3  
    

To install an extension by using the client

  1. In Dynamics 365 Business Central , use search to open the Extension Management page.In the Extension Management window, you can view the extensions that are published to your server. For each extension, you can see the current installation status.
  2. Choose an extension to see additional information and to install the extension.
  3. Review and accept the license agreement.
  4. Choose the Install button to install the extension.

See Also

Unpublishing and Uninstalling Extensions
Developing Extensions