Adicionando a função documentation

O Power Query gerará automaticamente uma interface do 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.

Note que as funções internas normalmente fornecem uma melhor experiência do usuário, com descrições, dicas de ferramenta 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 por Power Query e como você pode usá-los em suas extensões.

Função Types

Você pode fornecer documentation para sua função definindo valores type personalizados. O processo tem a seguinte aparência:

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

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

O uso dessa 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 da caixa de texto padrão em uma lista suspensa).

A experiência Power Query recupera a documentation de metadados no tipo de sua função, usando uma combinação de chamadas para Value.Type, Type.FunctionParameters e Value.Metadata.

Função documentation

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

Campo	Type	Detalhes
Documentation.Examples	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, Code e Result.
Documentation.LongDescription	text	Descrição completa do que a função faz, exibida nas informações da função.
Documentation.Name	text	Texto a ser exibido na parte superior da caixa de diálogo de invocação de função.

Parâmetro documentation

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

Campo	Type	Detalhes
Documentation.AllowedValues	lista	Lista de valores válidos para esse parâmetro. Desde que esse campo altere 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	text	Nome de exibição amigável a ser usado para o parâmetro.
Documentation.FieldDescription	text	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.
Formatting.IsMultiLine	boolean	Permite criar uma entrada de várias linhas, por exemplo, para colar em consultas nativas.
Formatação.IsCode	boolean	Formata o campo de entrada para código, normalmente 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 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 da função

Informações da função

Exemplo de multilinha

[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 na caixa de diálogo a seguir no Power BI. Novas linhas serão representadas em texto com '#(lf)' ou 'feed de linha'.