Uso de funciones personalizadas en Language GenerationUse custom functions in language generation

se aplica a: SDK V4APPLIES TO: SDK v4

Los desarrolladores pueden usar las funciones creadas previamente que admiten las expresiones adaptables y las funciones personalizadas en las plantillas de generación de lenguaje (LG).Developers can use both prebuilt functions supported by adaptive expressions and custom functions in language generation (LG) templates. En este artículo se muestra cómo agregar una función personalizada en el bot a expresiones adaptables y usar la función en una plantilla de LG.This article shows you how to add a custom function in your bot to adaptive expressions and use the function in an LG template.

PrerrequisitosPrerequisites

Sobre el ejemploAbout the sample

Este ejemplo de funciones personalizadas de LG es un ejemplo de cómo agregar una función personalizada simple a expresiones adaptables y, a continuación, usar esa expresión en una plantilla de LG.This LG custom functions sample is an example of how to add a simple custom function to adaptive expressions and then use that expression in an LG template. El bot solicita al usuario un número y, si la entrada es válida, devuelve la raíz cuadrada.The bot asks the user for a number, and if the input is valid returns the square root. La función que calcula la raíz cuadrada, contoso.sqrt , se define en la lógica de Bot y se usa en la plantilla de LG que genera las respuestas de bot.The function that computes the square root, contoso.sqrt, is defined in the bot logic, and is used in the LG template that generates bot responses.

En este artículo se usa un enfoque ascendente para agregar y usar funciones personalizadas en las plantillas de LG.This article uses a bottom up approach to adding and using custom functions in LG templates. Aprenderá a:You will learn about how to:

PaquetesPackages

Para usar expresiones adaptables y LG, instale los paquetes Microsoft. bot. Builder. LanguageGeneration y AdaptiveExpressions .To use adaptive expressions and LG, install the Microsoft.Bot.Builder.LanguageGeneration and AdaptiveExpressions packages. El ejemplo ya tiene el paquete instalado.The sample already has the packaged installed. Después, agregue el siguiente fragmento de código al archivo bot principal.Then add the following snippet to your main bot file.

Bots/CustomFunctionBot. CSBots/CustomFunctionBot.cs

using Microsoft.Bot.Builder.LanguageGeneration;
using AdaptiveExpressions;

Agregar una función personalizada a expresiones adaptablesAdd a custom function to adaptive expressions

Para usar funciones personalizadas en el bot, debe agregarlas a expresiones adaptables.To use custom functions in your bot, you need to add them to adaptive expressions. En esta sección se muestra cómo agregar una función personalizada denominada contoso.sqrt a expresiones adaptables.This section shows how to add a custom function named contoso.sqrt to adaptive expressions.

Comience agregando una constante de cadena con el nombre de la función personalizada al constructor de bot.Start by adding a string constant with the name of your custom function to your bot constructor. El nombre de la función debe ser corto pero reconocible.The name of your function should be short but recognizable. En este ejemplo, la función personalizada se denomina contoso.sqrt :In this sample, the custom function is named contoso.sqrt:

Bots/CustomFunctionBot. CSBots/CustomFunctionBot.cs

const string mySqrtFnName = "contoso.sqrt";

Importante

Anteponga el prefijo a las funciones para evitar colisiones de espacios de nombres.Prefix your functions to avoid namespace collisions.

En, el nombre de la función contoso es el prefijo y sqrt es una mano corta para la raíz cuadrada, que devuelve la función.In the function name contoso is the prefix and sqrt is short hand for square root, which the function returns.

Ahora puede definir la lógica de la función en el constructor de Bot y agregarla a expresiones adaptables mediante la Expression.Functions.Add() función.Now you can define the logic for your function in your bot constructor and add it to adaptive expressions using the Expression.Functions.Add() function. Al agregar la función personalizada a una expresión adaptable, se puede usar la función en las plantillas de LG, del mismo modo que con cualquiera de las funciones creadas previamente.Adding your custom function to adaptive expression makes it possible to use your function across LG templates, just as you can with any of the prebuilt functions.

En el siguiente fragmento de código se muestra cómo agregar una función, definida como mySqrtFnName , a las expresiones adaptables.The snippet below shows how to add a function, defined as mySqrtFnName, to adaptive expressions. Esta función devuelve la raíz cuadrada de un único argumento, args , si es válido, y null si no lo es:This function returns the square root of a single argument, args, if valid, and null if not not:

// Add custom sqrt function
Expression.Functions.Add(mySqrtFnName, (args) =>
{
    object retValue = null;
    if (args[0] != null)
    {
        double dblValue;
        if (double.TryParse(args[0], out dblValue))
        {
            retValue = Math.Sqrt(dblValue);
        }
    }
    return retValue;
});

Uso de la función personalizada en una plantilla de LGUse your custom function in an LG template

Después de agregar la función personalizada a las expresiones adaptables, puede usarla en las plantillas de LG.After adding your custom function to adaptive expressions you can use it in LG templates. En esta sección se describe cómo configurar la respuesta del bot en función de si la entrada del usuario era válida.This section describes how to set up the bot's response depending on whether the user input was valid.

Hay dos definiciones de plantilla en Main. LG: la plantilla de respuesta simple sqrtReadBack y la plantilla de respuesta condicional sqrtTemplate :There are two template definitions in main.lg: the simple response template sqrtReadBack and the conditional response template sqrtTemplate:

Resources/Main. LGResources/main.lg

# sqrtReadBack
- You said '${text}'. ${sqrtTemplate()}.

Esta plantilla genera una respuesta que contiene la entrada del usuario ${text} y el resultado de la segunda plantilla IF-Else condicional sqrtTemplate :This template generates a response that contains the user input, ${text} and the result of the second conditional if-else template sqrtTemplate:

# sqrtTemplate
- IF : ${contoso.sqrt(text) != null}
    - It's square root is ${coalesce(contoso.sqrt(text), 'NaN')}
- ELSE : 
    - Sqrt not possible.

En esta plantilla, el resultado de contoso.sqrt(text) se usa para determinar la respuesta:In this template, the result of contoso.sqrt(text) is used to determine the response:

  • Si el resultado no es null, se usa la línea del IF bloque en sqrtReadBack .If the result is not null, the line under the IF block is used in sqrtReadBack. Tenga en cuenta que esta línea utiliza una expresión insertada, ${coalesce(contoso.sqrt(text), 'NaN)} .Note that this line uses an inline expression, ${coalesce(contoso.sqrt(text), 'NaN)}. La función pregenerada Coalesce devuelve el resultado de contoso.sqrt(text) si no es NULL y NaN si es NULL.The prebuilt function coalesce returns the result of contoso.sqrt(text) if it is not null and NaN if it is null.
  • Si el resultado es null, se utiliza la línea del ELSE bloque en sqrtReadBack .If the result is null, the line under the ELSE block is used in sqrtReadBack.

Carga y uso de la plantilla de LG en el botLoad and use your LG template in your bot

Ahora que ha creado la plantilla de respuesta de bot sqrtReadBack en Main. LG, puede usar la plantilla en la lógica de bot.Now that you've created your bot's response template sqrtReadBack in main.lg, you can use the template in your bot's logic.

Para empezar, cree un Templates objeto privado denominado _templates .To start, create a private Templates object called _templates.

Bots/CustomFunctionBot. CSBots/CustomFunctionBot.cs

protected Templates _templates;

El _templates objeto se usa para hacer referencia a plantillas en los archivos. LG.The _templates object is used to reference templates in your .lg files.

A continuación, combine la ruta de acceso para la compatibilidad entre plataformas.Then combine the path for cross-platform support. Asegúrese de incluir Main. LG agregando lo siguiente:Make sure to include main.lg by adding the following:

var lgFilePath = Path.Join(Directory.GetCurrentDirectory(), "Resources", "main.lg");

Ahora puede analizar los archivos en lgFilePath y cargar las plantillas de LG, como se muestra a continuación.Now you can parse the files in lgFilePath and load your LG templates, as shown below. De forma predeterminada Expression.Function , usa, que incluye la función personalizada.By default this uses Expression.Function, which includes your custom function.

_templates = Templates.ParseFile(lgFilePath);

Ahora se cargan las plantillas y puede hacer referencia a ellas por su nombre en el bot.Your templates are now loaded and you can reference them by name in your bot. En este ejemplo, se usa el resultado de la evaluación sqrtReadBack como el que se replyText envía al usuario.In this sample, the result of evaluating sqrtReadBack is used as the replyText sent to the user.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var replyText = _templates.Evaluate("sqrtReadBack", turnContext.Activity);
    await turnContext.SendActivityAsync(ActivityFactory.FromObject(replyText), cancellationToken);
}

Ya está listo para probar el bot.You're now ready to test your bot.

Probar el botTest the bot

Descargue e instale la versión más reciente del emulador de bot Framework.Download and install the latest version of the Bot Framework Emulator.

  1. Ejecute el ejemplo localmente en la máquina.Run the sample locally on your machine. Si necesita instrucciones, consulte el archivo Léame del ejemplo de C#o JavaScript .If you need instructions, refer to the README file for the C#or Javascript sample.
  2. En el emulador, escriba cualquier cosa.In the Emulator, type anything. Observará que el emulador devolverá la raíz cuadrada de los números especificados y NaN para el resto de las entradas.You will notice that the Emulator will return the square root of numbers entered and NaN for all other input.

probar el bot

Información adicionalAdditional Information