Adicionando documentação da função

O Power Query gerará automaticamente uma interface de usuário de invocação para você com base nos argumentos da função. Por padrão, essa interface do usuário conterá o nome da função e uma entrada para cada um dos parâmetros.

Da mesma forma, avaliar o nome da função, sem especificar parâmetros, exibirá informações sobre ela.

Você pode notar que as funções internas normalmente fornecem uma melhor experiência do usuário, com descrições, dicas de ferramentas e até valores de exemplo. Você pode aproveitar esse mesmo mecanismo definindo meta-valores específicos em seu tipo de função. Este tópico descreve os meta campos usados pelo Power Query e como você pode usá-los em suas extensões.

Tipos de função

Você pode fornecer documentação para sua função definindo valores de tipo personalizados. O processo tem esta aparência:

1. Defina um tipo para cada parâmetro.
2. Defina um tipo para sua função.
3. Adicione vários Documentation.* campos ao registro de metadados de tipos.
4. Chame Value.ReplaceType para atribuir o tipo à função compartilhada.

Você pode encontrar mais informações sobre tipos e valores de metadados na Especificação de Linguagem M.

Usar essa abordagem permite fornecer descrições e exibir nomes para sua função, bem como parâmetros individuais. Você também pode fornecer valores de exemplo para parâmetros, bem como definir uma lista predefinida de valores (transformando o controle de caixa de texto padrão em uma lista suspensa).

A experiência do Power Query recupera a documentação a partir de valores meta no tipo da sua função, usando uma combinação de chamadas para Value.Type, Type.FunctionParameters e Value.Metadata.

Documentação da função

A tabela a seguir lista os campos documentação que podem ser definidos nos metadados da função. Todos os campos são opcionais.

Campo	Tipo	Detalhes
Documentação.Exemplos	lista	Lista de objetos de registro com o uso de exemplo da função. Exibido apenas como parte das informações da função. Cada registro deve conter os seguintes campos de texto opcionais: Description, Codee Result.
Documentation.LongDescription	enviar SMS	Descrição completa do que a função faz, exibida nas informações da função.
Documentação.Name	enviar SMS	Texto a ser exibido na parte superior da caixa de diálogo de invocação de função.

Documentação do parâmetro

A tabela a seguir lista os campos de documentação que podem ser definidos nos metadados dos seus parâmetros de função. Todos os campos são opcionais.

Campo	Tipo	Detalhes
Documentation.AllowedValues	lista	Lista de valores válidos para esse parâmetro. Fornecer este campo alterará a entrada de uma caixa de texto para uma lista suspensa. Observe que isso não impede que um usuário edite manualmente a consulta para fornecer valores alternativos.
Documentation.FieldCaption	enviar SMS	Nome de exibição amigável a ser usado para o parâmetro.
Documentação.DescriçãoDoCampo	enviar SMS	Descrição para mostrar ao lado do nome de exibição.
Documentation.SampleValues	lista	Lista de valores de exemplo a serem exibidos (como texto desbotado) dentro da caixa de texto.
Formatação.IsMultiLine	boolean	Permite que você crie um campo de entrada de várias linhas, por exemplo, para colar em consultas nativas.
Formatação.IsCode	boolean	Formata o campo de entrada para código, geralmente com entradas de várias linhas. Usa uma fonte semelhante a código em vez da fonte padrão.

Exemplo básico

O snippet de código a seguir (e as caixas de diálogo resultantes) são da amostra HelloWorldWithDocs .

[DataSource.Kind="HelloWorldWithDocs", Publish="HelloWorldWithDocs.Publish"]
shared HelloWorldWithDocs.Contents = Value.ReplaceType(HelloWorldImpl, HelloWorldType);

HelloWorldType = type function (
    message as (type text meta [
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

HelloWorldImpl = (message as text, optional count as number) as table =>
    let
        _count = if (count <> null) then count else 5,
        listOfMessages = List.Repeat({message}, _count),
        table = Table.FromList(listOfMessages, Splitter.SplitByNothing())
    in
        table;

Esse código resulta nas caixas de diálogo a seguir no Power BI.

Invocação de FunctionPrompt

Exemplo de várias linhas

[DataSource.Kind="HelloWorld", Publish="HelloWorld.Publish"]
shared HelloWorld.Contents =
    let
        HelloWorldType = type function (
            message1 as (type text meta [
                Documentation.FieldCaption = "Message 1",
                Documentation.FieldDescription = "Text to display for message 1",
                Documentation.SampleValues = {"Hello world"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = true
            ]),
            message2 as (type text meta [
                Documentation.FieldCaption = "Message 2",
                Documentation.FieldDescription = "Text to display for message 2",
                Documentation.SampleValues = {"Hola mundo"},
                Formatting.IsMultiLine = true,
                Formatting.IsCode = false
            ])) as text,
        HelloWorldFunction = (message1 as text, message2 as text) as text => message1 & message2
    in
        Value.ReplaceType(HelloWorldFunction, HelloWorldType);

Esse código (com informações de publicação associadas e assim por diante) resulta no diálogo a seguir no Power BI. Novas linhas serão representadas no texto com '#(lf)' ou 'line feed'.