Extend Composer with extensions

APPLIES TO: Composer v1.x and v2.x

Composer extensions are JavaScript modules. When loaded into Composer, the module is given access to a set of Composer APIs which can then be used by the extension to provide new functionality to the application. You can extend and customize the behavior of Composer by installing extensions which can hook into the internal mechanisms of Composer and change the way they operate. Extensions can also "listen to" the activity inside Composer and respond to it. In this article, you'll learn the following:

• Set up multi-user authentication via extensions.
• Set up customized storage and make storage user-aware.
• Add an interactable web view to Composer's navigation pane.
• Add a custom publishing extension and user experience from Composer.
• Provide an alternate version of the runtime template.

Prerequisites

• A basic understanding of Composer extensions.
• A clone of the Bot Framework Composer GitHub repository.

Set up multi-user authentication via extensions

By default, there's no authentication required to access the Composer application and anyone with the URL will be able to use it. Some mechanisms must be used to secure access to the application and the resources available to it.

This can be achieved using Composer's authentication and identity extension endpoint. Composer has adopted Passport.js as its primary auth mechanism. As a result, it's possible to use any of the 500+ compatible authentication systems with Composer through only a few lines of code.

In your clone of Composer, add the new extension under the /extensions folder. Make sure the package.json file is properly configured according to the instructions at the link above. Reload the Composer app, and the new extension should take affect automatically, requiring a login.

Read the API documentation for authentication and identity extensions.

Set up customized storage and make storage user-aware

By default, Composer will read and write bot projects from the local filesystem. All users have the same access to the filesystem.

To change the storage mechanism, or modify it to consider a user identity provided by an authentication extension, it's necessary to create a new extension that uses the storage extension endpoint.

By providing a custom storage implementation, it's possible to restrict a user's access to content using something like user ID. It's also possible to completely replace the storage mechanism used by Composer, for example, using a hosted database instead of the local filesystem.

Read the API documentation for storage extensions.

Add an interactable web view to Composer's navigation pane

Composer supports adding extensions that render custom user interfaces inside the application and allows these user interfaces to read and modify Composer's active application state. By configuring the extension's package.json definition to add itself as a contribution point to the Composer's navigation pane, it shows up in the application. An example of this is on GitHub.

The full code for Package Manager is in the BotFramework-Composer repository.

Add a custom publishing extension and user experience from Composer

Similarly to adding a reference to a page in Composer's navigation pane, users can add a custom publishing and deployment experience inside Composer's Publish page as its own contribution point. Composer's support of publishing to Power Virtual Agents is an example of this. For an example of the contribution point, see a sample publish element.

For the full code for Composer's Power Virtual Agents publishing extension, see the pvaPublish folder in the BotFramework-Composer repo.

Provide an alternate version of the runtime template

Sometimes it's necessary to modify the code of the runtime used to operate the bots, for example, to install different packages or bundle new features.

This is possible by modifying the runtime template that's generated with Composer. Composer supports C# .NET and JavaScript solutions located in the root of the project directory when created.

When a user selects Start bot or uses Composer's publishing system, Composer will use this structure as the source of truth of what's deployed. Changes made to the template in this folder will automatically be used.

It's also possible to specify one or more alternate runtimes that can be made available as part of a bot project template, or as an option for users to choose in each bot's settings.

For more information read the API documentation for providing runtime templates.