diff --git a/README.md b/README.md index 7d05e49f79..57de73eeec 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ You'll primarily use components through [**Bot Framework Composer**](https://git ## Creating your own components -You can also create your own packages and templates for use from Composer. We document creating components [here](/docs/overview.md). You can use this repository as examples for building your own components. +You can also create your own packages and templates for use from Composer. We document creating components [here](https://docs.microsoft.com/composer/concept-packages). You can also check out [our samples](https://github.com/microsoft/BotBuilder-Samples/tree/main/composer_samples). ## Index of Content diff --git a/assets/packageManager.PNG b/assets/packageManager.PNG deleted file mode 100644 index 414d6d4797..0000000000 Binary files a/assets/packageManager.PNG and /dev/null differ diff --git a/docs/assets/MultiplyDialog.cs b/docs/assets/MultiplyDialog.cs deleted file mode 100644 index 3b3b46177c..0000000000 --- a/docs/assets/MultiplyDialog.cs +++ /dev/null @@ -1,81 +0,0 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. -// Licensed under the MIT License. - -using System; -using System.Runtime.CompilerServices; -using System.Threading; -using System.Threading.Tasks; -using AdaptiveExpressions.Properties; -using Microsoft.Bot.Builder.Dialogs; -using Newtonsoft.Json; - -namespace CustomAction.MultiplyDialog -{ - /// - /// Custom command which takes takes 2 data bound arguments (arg1 and arg2) and multiplies them returning that as a databound result. - /// - public class MultiplyDialog : Dialog - { - [JsonConstructor] - public MultiplyDialog([CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0) - : base() - { - // enable instances of this command as debug break point - this.RegisterSourceLocation(sourceFilePath, sourceLineNumber); - } - - /// - /// Gets the unique name of this Adaptive Dialog. - /// - [JsonProperty("$kind")] - public const string Kind = "MultiplyDialog"; - - /// - /// Gets or sets memory path to bind to arg1 (ex: action.arg1). - /// - /// - /// Memory path to bind to arg1 (ex: action.arg1). - /// - [JsonProperty("arg1")] - public NumberExpression Arg1 { get; set; } - - /// - /// Gets or sets memory path to bind to arg2 (ex: action.arg2). - /// - /// - /// Memory path to bind to arg2 (ex: action.arg2). - /// - [JsonProperty("arg2")] - public NumberExpression Arg2 { get; set; } - - /// - /// Gets or sets caller's memory path to store the result of this step in (ex: dialog.result). - /// - /// - /// Caller's memory path to store the result of this step in (ex: dialog.result). - /// - /// - /// This is where the result of the Dialog is stored and accessible in Composer. - /// - [JsonProperty("resultProperty")] - public StringExpression ResultProperty { get; set; } - - /// - /// Override BeginDialogAsync to provide the custom action functionality. The inputs, in this case, - /// are define in Arg1 and Arg2. The result of the the dialog is stored in ResultProperty. - /// - public override Task BeginDialogAsync(DialogContext dc, object options = null, CancellationToken cancellationToken = default(CancellationToken)) - { - var arg1 = Arg1.GetValue(dc.State); - var arg2 = Arg2.GetValue(dc.State); - - var result = Convert.ToInt32(arg1) * Convert.ToInt32(arg2); - if (this.ResultProperty != null) - { - dc.State.SetValue(this.ResultProperty.GetValue(dc.State), result); - } - - return dc.EndDialogAsync(result: result, cancellationToken: cancellationToken); - } - } -} diff --git a/docs/assets/MultiplyDialog.csproj b/docs/assets/MultiplyDialog.csproj deleted file mode 100644 index b070533348..0000000000 --- a/docs/assets/MultiplyDialog.csproj +++ /dev/null @@ -1,27 +0,0 @@ - - - - Library - netcoreapp3.1 - CustomAction.MultiplyDialog - This library implements .NET support for the MultiplyDialog custom action sample BotComponent. - This library implements .NET support for the MultiplyDialog custom action sample BotComponent. - content - - msbot-component;msbot-action - - - - - - - - - - - - - - - - diff --git a/docs/assets/MultiplyDialog.schema b/docs/assets/MultiplyDialog.schema deleted file mode 100644 index f2928a25aa..0000000000 --- a/docs/assets/MultiplyDialog.schema +++ /dev/null @@ -1,25 +0,0 @@ -{ - "$schema": "https://schemas.botframework.com/schemas/component/v1.0/component.schema", - "$role": "implements(Microsoft.IDialog)", - "title": "Multiply", - "description": "This will return the result of arg1*arg2", - "type": "object", - "additionalProperties": false, - "properties": { - "arg1": { - "$ref": "schema:#/definitions/integerExpression", - "title": "Arg1", - "description": "Value from callers memory to use as arg 1" - }, - "arg2": { - "$ref": "schema:#/definitions/integerExpression", - "title": "Arg2", - "description": "Value from callers memory to use as arg 2" - }, - "resultProperty": { - "$ref": "schema:#/definitions/stringExpression", - "title": "Result", - "description": "Value from callers memory to store the result" - } - } -} \ No newline at end of file diff --git a/docs/assets/MultiplyDialogBotComponent.cs b/docs/assets/MultiplyDialogBotComponent.cs deleted file mode 100644 index 2d5903e7dd..0000000000 --- a/docs/assets/MultiplyDialogBotComponent.cs +++ /dev/null @@ -1,33 +0,0 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. -// Licensed under the MIT License. - -using Microsoft.Bot.Builder; -using Microsoft.Bot.Builder.Dialogs.Declarative; -using Microsoft.Extensions.Configuration; -using Microsoft.Extensions.DependencyInjection; - -namespace CustomAction.MultiplyDialog -{ - /// - /// Definition of a that allows registration of - /// services, custom actions, memory scopes and adapters. - /// - /// To make your components available to the system you derive from BotComponent and register services to add functionality. - /// These components then are consumed in appropriate places by the systems that need them. When using Composer, Startup gets called - /// automatically on the components by the bot runtime, as long as the components are registered in the configuration. - public class MultiplyDialogBotComponent : BotComponent - { - /// - /// Entry point for bot components to register types in resource explorer, consume configuration and register services in the - /// services collection. - /// - /// Services collection to register dependency injection. - /// Configuration for the bot component. - public override void ConfigureServices(IServiceCollection services, IConfiguration configuration) - { - // Anything that could be done in Startup.ConfigureServices can be done here. - // In this case, the MultiplyDialog needs to be added as a new DeclarativeType. - services.AddSingleton(sp => new DeclarativeType(MultiplyDialog.Kind)); - } - } -} diff --git a/docs/creating-packages.md b/docs/creating-packages.md deleted file mode 100644 index 322a2ccc94..0000000000 --- a/docs/creating-packages.md +++ /dev/null @@ -1,104 +0,0 @@ -# Creating packages - ->Note: If you are not familiar with creating [NuGet](https://nuget.org) or [npm](https://npmjs.com) packages in general, you may want to consult their documentation to ensure you understand the basics. - -Packages are bits of bots that you want to reuse and/or share. They are simply standard NuGet or npm packages that contain any combination of the items listed below. - -- Complete sets of dialog files -- Coded extensions like - - Custom actions and triggers - - Middleware - - Adapters - -At a high level, the steps for creating a package are: - -1. Create your dialog files (use Composer to create them). -2. Create your code extensions (use your favorite IDE to create them). -3. Let Composer know about your package contents with schema files. -4. Register your code extensions with the runtime through the `BotComponent` class. -5. Package your files (use NuGet for C# runtime bots, and npm for bots using the JavaScript runtime). -6. Publish your package to a package feed (public, private, or local). - -When your package is added to a bot from Package Manager in Composer, the following steps happen: - -1. The package is installed using `nuget|npm install`. -2. Your declarative files are merged using the [Bot Frameowork CLI's](https://github.com/microsoft/botframework-cli) `dialog:merge` command. - 1. `dialog:merge` adds a copy of any dialog assets (.lu/.lg/.qna/.dialog files) in your package to the corresponding folding in the bot project. - -> Note: While testing and debugging your package, you may find it useful to manually install and merge your package from the command line, rather than from Composer. - -## Declarative files in packages - -Declarative files can be added to your package by placing them in a an `exported` folder in your package. You need to include a complete set of dialog files in order for Composer to recognize them. Use Composer to create your dialog, then add the complete dialog folder to your package. The folder structure should look similar to the below (depending on language encoding): - -- Exported - - YourDialogName - - knowledge-base/en-us - - en-us - - YourDialogName.en-us.qna - - language-generation - - en-us - - YourDialogName.en-us.lg - - language-understanding - - en-us - - YourDialogName.en-us.lu - - recognizers - - YourDialogName.en-us.dialog - - YourDialogName.lu.dialog - - YourDialogName.qna.dialog - - YourDialogName.dialog - -See the [Help and Cancel](/packages/HelpAndCancel) package for an example of a package containing a dialog. - -## Code extensions in packages - -The contents of your package are essentially the same as what you would create if you were [extending your bot with code](/docs/extending-with-code.md). Just make sure you're using the `BotComponent` class to register your components. - -### BotComponent - -To dynamically register your action with the Adaptive Runtime, you'll need to define a BotComponent by inheriting from the Microsoft.Bot.Builder.BotComponent class. For example, here is how you register a simple custom action called MyCustomAction: - -```c# -using Microsoft.Bot.Builder; -using Microsoft.Bot.Builder.Dialogs.Declarative; -using Microsoft.Extensions.Configuration; -using Microsoft.Extensions.DependencyInjection; - -namespace MyBot -{ - public class MyBotComponent : BotComponent - { - public override void ConfigureServices(IServiceCollection services, IConfiguration configuration) - { - // Component type - services.AddSingleton(sp => new DeclarativeType(MyCustomAction.Kind)); - } - } -} -``` - -## Packaging your files - -You'll package your components using the normal `pack` command for your package type (NuGet or npm). Be sure to include any necessary declarative files, as they are typically not included by default (for NuGet, you'd add them in either the .proj or .nuspec file). - -## Publishing your package - -You can publish your package to a local feed, or to a hosted feed (private or public). If you are planning to publish to NuGet or npm, and wish to make your package available from the default feeds in Package Manager in Composer, then you'll need to use the 'msbot-component' tag on your package. - -Optionally, you can also use one or more of the following tags based on the contents of your package. - -- msbot-content -- msbot-middleware -- msbot-action -- msbot-trigger -- msbot-adapter - -The easiest thing to do is to publish to a local feed. Read about doing that here: [Setting up Local NuGet Feeds](https://docs.microsoft.com/nuget/hosting-packages/local-feeds). - -## Docs table of contents - -1. [Overview](/docs/overview.md) -2. [Extending your bot using packages](/docs/extending-with-packages.md) -3. [Extending your bot with code](/docs/extending-with-code.md) -4. [Creating your own packages](/docs/creating-packages.md) -5. [Creating your own templates](/docs/creating-templates.md) diff --git a/docs/creating-templates.md b/docs/creating-templates.md deleted file mode 100644 index 1e970740b4..0000000000 --- a/docs/creating-templates.md +++ /dev/null @@ -1,11 +0,0 @@ -# Creating templates - -Coming Soon! - -## Docs table of contents - -1. [Overview](/docs/overview.md) -2. [Extending your bot using packages](/docs/extending-with-packages.md) -3. [Extending your bot with code](/docs/extending-with-code.md) -4. [Creating your own packages](/docs/creating-packages.md) -5. [Creating your own templates](/docs/creating-templates.md) diff --git a/docs/extending-with-code.md b/docs/extending-with-code.md deleted file mode 100644 index 30672bad5b..0000000000 --- a/docs/extending-with-code.md +++ /dev/null @@ -1,160 +0,0 @@ -# Extending your bot with code - -# Add custom actions in C# - -## In this article - -In Bot Framework Composer, [actions](concept-dialog#action) are the main -contents of a [trigger](concept-dialog#trigger). Actions help maintain -conversation flow and instruct bots on how to fulfill user requests. -Composer provides different types of actions, such as **Send a -response**, **Ask a question**, and **Create a condition**. Besides -these built-in actions, you can create and customize your own actions in -Composer. - -This article shows you how to include a custom action named -`MultiplyDialog`. - -#### Note - -Composer currently supports the C\# runtime and JavaScript (preview) -Adaptive Runtimes. - -## Prerequisites - -- A basic understanding of [actions](concept-dialog#action) in Composer. -- [A basic bot built using Composer](quickstart-create-bot). -- [Bot Framework CLI 4.10](https://botbuilder.myget.org/feed/botframework-cli/package/npm/@microsoft/botframework-cli) or later. - -## Setup the Bot Framework CLI tool ----------------------- - -The Bot Framework CLI tools include the *bf-dialog* tool which will -create a *schema file* that describes the built-in and custom -capabilities of your bot project. It does this by merging partial schema -files included with each component with the root schema provided by Bot -Framework. - -Open a command line and run the following command to install the Bot -Framework tools: - - npm i -g @microsoft/botframework-cli - -## About this custom action ----------------------- - -This C\# custom action consists of the following: - -- A Composer project targeted for Dotnet. This can be any Composer project. One that already exists, or a new one you create. If you want to experiment risk free, create a new Blank Bot in Composer. This document assumes you create a Blank Bot named "MyBlankBot". - -- The custom action code [MultiplyDialog.cs](assets/MultiplyDialog.cs) class, which defines the business logic of the custom action. In this example, two numbers passed as inputs are multiplied, and the result is the output. - -- The custom action schema [MultiplyDialog.schema](assets/MultiplyDialog.schema), which describes the operations available. - - [Bot Framework Schemas](https://github.com/microsoft/botframework-sdk/tree/master/schemas) - are specifications for JSON data. They define the shape of the data - and can be used to validate JSON. All of Bot Framework's [adaptive - dialogs](/en-us/azure/bot-service/bot-builder-adaptive-dialog-introduction) - are defined using this JSON schema. The schema files tell Composer - what capabilities the bot runtime supports. Composer uses the schema - to help it render the user interface when using the action in a - dialog. Read the section about [creating schema files in adaptive - dialogs](/en-us/azure/bot-service/bot-builder-dialogs-declarative) - for more information. - -- A BotComponent, [MultiplyDialogBotComponent.cs](assets/MultiplyDialogBotComponent.cs) code file for component registration. BotComponents are loaded by your bot (specifically by Adaptive Runtime), and made available to Composer. - - **Note** You can create a custom action without implementing BotComponent. However, the Component Model in Bot Framework allows for easier reuse and is only slightly more work. In a BotComponent, you add the needed services and objects via Dependency Injection, just as you would in Startup.cs. - -## Adding the custom action to your bot project ------------------------------- - -1. Navigate to your Composer bot project folder (eg. C:\MyBlankBot) and create a new folder for the custom action project. For example, C:\MyBlankBot\MultiplyDialog. - -1. Save [MultiplyDialog.cs](assets/MultiplyDialog.cs), [MultiplyDialog.schema](assets/MultiplyDialog.schema), [MultiplyDialog.csproj](assets/MultiplyDialog.csproj), and [MultiplyDialogBotComponent.cs](assets/MultiplyDialogBotComponent.cs) to this new folder. - -1. Open your Blank Bot solution (C:\MyBlankBot) in Visual Studio. - -1. Add Existing project to the solution. - -1. In the MyBlankBot project, add a project reference to the MultiplyDialog project. Alternatively, you can add `` to the appropriate `ItemGroup` in MyBlankBot.csproj. - -1. Run the command `dotnet build` on the project to - verify if it passes build after adding custom actions to it. You - should be able to see the "Build succeeded" message after this - command. - -1. Edit MyBlankBot\settings\appsettings.json to include the MultiplyDialogBotComponent in the `runtimeSettings/components` list. - - ```json - "runtimeSettings": { - "components": [ - { - "name": "CustomAction.MultiplyDialog" - } - ] - } - ``` - -## Update the schema file ----------------------- - -Now you have customized your bot, the next step is to update the -`sdk.schema` file to include the `MultiplyDialog.Schema` file. This makes your custom action available for use in Composer. - -**You only need to perform these steps when adding new code extensions, or when the Schema for a component changes.** - -1) Navigate to the `C:\MyBlankBot\MyBlankBot\schemas` folder. This -folder contains a PowerShell script and a bash script. Run either one of -the following commands: - - ./update-schema.ps1 - - **Note** - - The above steps should generate a new `sdk.schema` file inside the - `schemas` folder. - -1) Search for `MultiplyDialog` inside the `MyBlankBot\schemas\sdk.schema` file and - validate that the partial schema for [MultiplyDialog.schema](assets/MultiplyDialog.schema) is included in `sdk.schema`. - -### Tip - -Alternatively, you can select the `update-schema.sh` file inside the -`MyBlankBot\schemas` folder to run the bash script. You can't click and run the -`powershell` file directly. - -## Test ----- - -Open the bot project in Composer and you should be able to test your -added custom action. If the project is already loaded, return to `Home` in Composer, and reload the project. - -1. Open your bot in Composer. Select a trigger you want to associate this custom action with. - -2. Select **+** under the trigger node to see the actions menu. You - will see **Custom Actions** added to the menu. Select **Multiply** - from the menu. - -3. On the **Properties** panel on the right side, enter two numbers in - the argument fields: **Arg1** and **Arg2**. Enter **dialog.result** - in the **Result** property field. For example, enter `99` for each field. - -4. Add a **Send a response** action. Enter `99*99=${dialog.result}` in the Language Generation editor. - -5. Select **Restart Bot** to test the bot in the Emulator. Your bot - will respond with the test result. - -## Additional information ----------------------- - -- [Bot Framework SDK Schemas](https://github.com/microsoft/botframework-sdk/tree/master/schemas) -- [Create schema files](/en-us/azure/bot-service/bot-builder-dialogs-declarative) - -## Docs table of contents - -1. [Overview](/docs/overview.md) -2. [Extending your bot using packages](/docs/extending-with-packages.md) -3. Extending your bot with code (this document) -4. [Creating your own packages](/docs/creating-packages.md) -5. [Creating your own templates](/docs/creating-templates.md) diff --git a/docs/extending-with-packages.md b/docs/extending-with-packages.md deleted file mode 100644 index 09729adfb0..0000000000 --- a/docs/extending-with-packages.md +++ /dev/null @@ -1,59 +0,0 @@ -# Extending your bot with packages - -Packages are bits of a bot you want to share/import like declarative dialog assets, coded dialogs, custom adapters, middleware or custom actions. They are just regular NuGet or npm packages (depending on the code language for your bot). You'll use the Bot Framework CLI tool to merge the package's declarative contents with your bot (package management in Composer will handle this for you, or you could do it yourself using the Bot Framework CLI tool). They can be made up of any combination of declarative assets (.dialog, .lu, .lg, .qna files), coded extensions (custom actions, middleware, adapters), or just plain old package libraries. - -Packages that contain dialog assets **differ from packages you've worked with in the past** slightly. Normally files and libraries contained in a package are not intended to be edited directly, however with declarative assets it is very likely that you will want to alter them to meet your needs. To support this, declarative assets from packages are _merged_ into your bot project, and a copy is created for you to edit. Once you've edited those assets, attempting to upgrade your package will cause a conflict and you'll need to determine manually how to manage merging your edits with the new version of the package. - -## Using Bot Framework Composer - -> Not seeing the Package Manager? Make sure you've enabled the Component Model feature flag in your Composer settings. - -You can open Package Manager with the bottom icon on the left navigation rail. - -![Package Manager](./assets/packageManager.png) - -From there, you can search for, add, update, or remove packages from your bot project. Package manager filters the list of packages to those tagged with `msbot-component` when connected to a public feed, so you will not see all packages your bot project takes a dependency on (you can open your project with an IDE like Visual Studio to see all your package dependencies). - -Remember, because declarative assets are merged from a package into your bot project, there may be conflicts. Pay attention if Composer warns you that an action may be destructive. - -### Connecting to custom feeds - -Package Manager will connect to the primary public package feed based on your bot project's language (for example, C# bots will be connected to NuGet by default). You can however connect to other public feeds, private feeds, or even local feeds to source your packages from. To do so, click on the **Edit Feeds** button and add your feed to the list. When working with local packages, make sure you've created a feed and added your package to it. See the [NuGet documentation](https://docs.microsoft.com/en-us/nuget/hosting-packages/local-feeds) on local feeds for more information. - -## Using CLI Tooling - -To install packages from the command line, use the normal package installation tool for your bot's programming language: - -**With a Node.js runtime:** - -Navigate to the bot project folder containing the package.json file and run: - -```bash -cd {BOT_NAME} -npm install --save [some package] -``` - -**With a C# runtime:** - -Navigate to the bot project folder containing the .csproj file and run: - -```bash -cd {BOT_NAME} -dotnet add package [some package] --version=[some version] -``` - -After running one of these commands, the package will be listed in the appropriate place, either the `package.json` or the `.csproj` file of the project. Now, use the Bot Framework CLI tool to extract any included dialog, lu and lg files, as well as to merge any new schema items. Run the following command: - -```bash -bf dialog:merge [package.json or .csproj] --imports /dialogs/imported --output /schemas/sdk -``` - -The output of the CLI tool will include a list of the files that were added, deleted or updated. Note that **changes to existing files will be overwritten if newer versions are found in a package.** - -## Docs table of contents - -1. [Overview](/docs/overview.md) -2. [Extending your bot using packages](/docs/extending-with-packages.md) -3. [Extending your bot with code](/docs/extending-with-code.md) -4. [Creating your own packages](/docs/creating-packages.md) -5. [Creating your own templates](/docs/creating-templates.md) diff --git a/docs/overview.md b/docs/overview.md deleted file mode 100644 index 8c6a1f318b..0000000000 --- a/docs/overview.md +++ /dev/null @@ -1,29 +0,0 @@ -# The Component Model - -The component model for building bots is our framework for sharing and reusing bot functionality - through new bots with templates, using portions of bots in the form of packages, or as complete bots with skills. - -## Table of Contents - -1. [Overview](/docs/overview.md) -2. [Extending your bot using packages](/docs/extending-with-packages.md) -3. [Extending your bot with code](/docs/extending-with-code.md) -4. [Creating your own packages](/docs/creating-packages.md) -5. [Creating your own templates](/docs/creating-templates.md) - -## Adaptive Runtime - -At the core of the component model is the adaptive runtime - an extensible, configurable runtime for your bot that is treated as a black box to bot developers and taken as a dependency. The runtime wraps the Bot Framework SDK, and provides extensibility points to add additional functionality by importing packages, connection to skills, or adding your own coded extensions. - -## Packages - -Packages are bits of a bot you want to reuse. They can contain things like declarative dialogs, coded dialogs, custom adapters, or custom actions. They are just regular NuGet or npm packages (depending on the code language for your bot). You'll use the Bot Framework CLI tool to merge the package's declarative contents with your bot (package management in Composer will handle this for you, or you could do it yourself using the Bot Framework CLI tool). They can be made up of any combination of declarative dialogs, coded extensions (custom actions, adapters), or just plain old package libraries. - -## Templates - -Getting started templates are created on top of the component model. They are built primarily by composing packages - ensuring that no matter which template you start from you'll have the flexibility to grow and develop your bot to meet your needs. - -For example, the Conversational Core template will take a dependency on two packages - welcome and help & cancel. It will also include a root dialog that wires up the dialogs in those packages as well as a dialog for handling unknown intents. This represents the base set of functionality nearly all conversational bots include. If you were to start from the empty/echo bot template, you could choose to add these packages later - either way you'd get the same set of functionality (without the need to do something like compare code samples and try and stitch them together yourself). - -## Skills - -Skills are separate bots you connect your bot to in order to process messages for you. The skill manifest establishes a contract other bots can follow - defining messages and events the skill can handle and any data that will be returned when the skill completes its interaction with your user.