Adicionar documentação da função

O Power Query gera automaticamente uma interface de invocação com base nos argumentos da sua função. Por padrão, essa interface do usuário contém 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 exibe 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 artigo descreve os meta campos que Power Query usa 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 do seu tipo.
4. Chame Value.ReplaceType para atribuir o tipo à função compartilhada.

Para obter mais informações sobre tipos e valores de metadados, consulte a Especificação da Linguagem M.

Usando essa abordagem, você pode fornecer descrições e exibir nomes para sua função e parâmetros individuais. Você também pode fornecer valores de exemplo para parâmetros e 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 de metadados no tipo da sua função por meio de uma combinação de chamadas a Value.Type, Type.FunctionParameters e Value.Metadata.

Documentação da função

A tabela a seguir lista os campos de documentação que você pode definir 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 você pode definir nos metadados para 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. Especificar este campo altera o campo de entrada de uma caixa de texto para uma lista suspensa. Observe que essa alteração 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 vêm do exemplo 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 cria os seguintes diálogos no Power BI.

Invocação da função

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) cria a caixa de diálogo a seguir em Power BI. Novas linhas aparecem no texto como #(lf), ou line feed.