Aggiunta della documentazione della funzione

Power Query genererà automaticamente un'interfaccia utente di chiamata in base agli argomenti per la funzione. Per impostazione predefinita, questa interfaccia utente conterrà il nome della funzione e un input per ognuno dei parametri.

Analogamente, la valutazione del nome della funzione, senza specificare i parametri, visualizzerà informazioni su di esso.

È possibile notare che le funzioni predefinite offrono in genere un'esperienza utente migliore, con descrizioni, descrizioni comandi e anche valori di esempio. È possibile sfruttare questo stesso meccanismo definendo valori meta specifici nel tipo di funzione. Questo argomento descrive i meta campi usati da Power Query e come usarli nelle estensioni.

Tipi di funzioni

È possibile fornire la documentazione per la funzione definendo valori di tipo personalizzati. Il processo è simile al seguente:

1. Definire un tipo per ogni parametro.
2. Definire un tipo per la funzione.
3. Aggiungere vari Documentation.* campi al record di metadati dei tipi.
4. Chiamare Value.ReplaceType per attribuire il tipo alla funzione condivisa.

Altre informazioni sui tipi e i valori dei metadati sono disponibili nella specifica del linguaggio M.

L'uso di questo approccio consente di fornire descrizioni e nomi visualizzati per la funzione, nonché di singoli parametri. È anche possibile specificare valori di esempio per i parametri, nonché definire un elenco predefinito di valori (trasformando il controllo casella di testo predefinito in un elenco a discesa).

L'esperienza di Power Query recupera la documentazione dai metadati sul tipo di funzione, usando una combinazione di chiamate a Value.Type, Type.FunctionParameters e Value.Metadata.

Documentazione della funzione

Nella tabella seguente sono elencati i campi della documentazione che possono essere impostati nei metadati per la funzione. Tutti i campi sono facoltativi.

Campo	Type	Details
Documentation.Examples	list	Elenco di oggetti record con utilizzo di esempio della funzione. Viene visualizzato solo come parte delle informazioni sulla funzione. Ogni record deve contenere i campi di testo facoltativi seguenti: Description, Codee Result.
Documentation.LongDescription	Testo	Descrizione completa delle operazioni della funzione, visualizzate nelle informazioni sulla funzione.
Documentation.Name	Testo	Testo da visualizzare nella parte superiore della finestra di dialogo di chiamata della funzione.

Documentazione dei parametri

Nella tabella seguente sono elencati i campi della documentazione che possono essere impostati nei metadati per i parametri della funzione. Tutti i campi sono facoltativi.

Campo	Type	Details
Documentation.AllowedValues	list	Elenco di valori validi per questo parametro. Se si specifica questo campo, l'input verrà modificato da una casella di testo a un elenco a discesa. Si noti che non impedisce a un utente di modificare manualmente la query per fornire valori alternativi.
Documentation.FieldCaption	Testo	Nome visualizzato descrittivo da usare per il parametro .
Documentation.FieldDescription	Testo	Descrizione da visualizzare accanto al nome visualizzato.
Documentation.SampleValues	list	Elenco di valori di esempio da visualizzare (come testo sbiadito) all'interno della casella di testo.
Formatting.IsMultiLine	boolean	Consente di creare un input su più righe, ad esempio per incollare le query native.
Formatting.IsCode	boolean	Formatta il campo di input per il codice, in genere con input su più righe. Usa un tipo di carattere simile al codice anziché il tipo di carattere standard.

Esempio di base

Il frammento di codice seguente (e i dialoghi risultanti) provengono dall'esempio 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;

Questo codice genera le finestre di dialogo seguenti in Power BI.

Chiamata di funzione

Informazioni sulla funzione

Esempio su più righe

[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);

Questo codice (con le informazioni di pubblicazione associate e così via) comporta la finestra di dialogo seguente in Power BI. Le nuove righe verranno rappresentate nel testo con '#(lf)' o 'avanzamento riga'.