Adicionando documentação de função

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

Da mesma forma, avaliar o nome da sua 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é mesmo valores de exemplo. Você pode tirar proveito desse mesmo mecanismo definindo metavalores específicos em seu tipo de função. Este tópico descreve os metacampos utilizados pelo Power Query e como pode utilizá-los nas suas extensões.

Tipos de função

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

1. Defina um tipo para cada parâmetro.
2. Defina um tipo para a sua função.
3. Adicione vários Documentation.* campos ao seu 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 que você forneça descrições e nomes de exibição 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 documentação de metavalores sobre o tipo da sua função, utilizando 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 sua função. Todos os campos são opcionais.

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

Documentação de parâmetros

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

Campo	Type	Detalhes
Documentation.AllowedValues	list	Lista de valores válidos para este 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.
Documentação.FieldCaption	texto	Nome de exibição amigável para usar para o parâmetro.
Documentação.CampoDescrição	texto	Descrição a ser exibida ao lado do nome para exibição.
Documentation.SampleValues	list	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, geralmente com entradas de várias linhas. Usa uma fonte semelhante a um código em vez da fonte padrão.

Exemplo básico

O trecho de código a seguir (e as caixas de diálogo resultantes) são 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 resulta nas seguintes caixas de diálogo no Power BI.

Invocação de função

Informaçã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) resulta na seguinte caixa de diálogo no Power BI. Novas linhas serão representadas no texto com '#(lf)', ou 'feed de linha'.