İşlev belgeleri ekleme

Power Query, işlevinizin bağımsız değişkenlerine göre sizin için otomatik olarak bir çağırma kullanıcı arabirimi oluşturur. Varsayılan olarak, bu kullanıcı arabirimi işlevinizin adını ve parametrelerinizin her biri için bir giriş içerir.

Benzer şekilde, parametre belirtmeden işlevinizin adını değerlendirerek bu işlevle ilgili bilgiler görüntülenir.

Yerleşik işlevlerin genellikle açıklamalar, araç ipuçları ve hatta örnek değerlerle daha iyi bir kullanıcı deneyimi sağladığını fark edebilirsiniz. İşlev türünüzde belirli meta değerleri tanımlayarak aynı mekanizmadan yararlanabilirsiniz. Bu konu başlığında Power Query tarafından kullanılan meta alanları ve uzantılarınızda bunları nasıl kullanabileceğiniz açıklanmaktadır.

İşlev Türleri

Özel tür değerleri tanımlayarak işlevinize yönelik belgeler sağlayabilirsiniz. İşlem şöyle görünür:

1. Her parametre için bir tür tanımlayın.
2. İşleviniz için bir tür tanımlayın.
3. Türlerinizin meta veri kaydına çeşitli Documentation.* alanlar ekleyin.
4. Türü paylaşılan işlevinize atamak için Value.ReplaceType öğesini çağırın.

Türler ve meta veri değerleri hakkında daha fazla bilgiyi M Dil Belirtimi'nde bulabilirsiniz.

Bu yaklaşımı kullanmak, işlevinizin açıklamalarını ve görünen adlarının yanı sıra tek tek parametreleri sağlamanıza olanak tanır. Ayrıca parametreler için örnek değerler sağlayabilir ve önceden ayarlanmış bir değer listesi tanımlayabilirsiniz (varsayılan metin kutusu denetimini açılan listeye dönüştürebilirsiniz).

Power Query deneyimi, Value.Type, Type.FunctionParameters ve Value.Metadata çağrılarının birleşimini kullanarak işlevinizin türüne ilişkin meta değerlerden belge alır.

İşlev belgeleri

Aşağıdaki tabloda, işlevinizin meta verilerinde ayarlanabilen Belge alanları listelenir. Tüm alanlar isteğe bağlıdır.

Alan	Türü	Ayrıntılar
Documentation.Examples	listele	İşlevin örnek kullanımına sahip kayıt nesnelerinin listesi. Yalnızca işlev bilgilerinin bir parçası olarak görüntülenir. Her kayıt şu isteğe bağlı metin alanlarını içermelidir: Description, Codeve Result.
Documentation.LongDescription	text	İşlevin ne yaptığının tam açıklaması, işlev bilgilerinde görüntülenir.
Documentation.Name	text	İşlev çağırma iletişim kutusunun üst kısmında görüntülenecek metin.

Parametre belgeleri

Aşağıdaki tabloda, işlev parametrelerinizin meta verilerinde ayarlanabilen Belge alanları listelenir. Tüm alanlar isteğe bağlıdır.

Alan	Türü	Ayrıntılar
Documentation.AllowedValues	listele	Bu parametre için geçerli değerlerin listesi. Bu alanın sağlanması, metin kutusundan gelen girişi açılan listeye değiştirir. Bu, kullanıcının alternatif değerler sağlamak için sorguyu el ile düzenlemesini engellemez.
Documentation.FieldCaption	text	Parametre için kullanılacak kolay görünen ad.
Documentation.FieldDescription	text	Görünen adın yanında gösterilecek açıklama.
Documentation.SampleValues	listele	Metin kutusunun içinde görüntülenecek örnek değerlerin listesi (soluk metin olarak).
Formatting.IsMultiLine	boolean	Yerel sorgulara yapıştırma gibi çok satırlı bir giriş oluşturmanıza olanak tanır.
Formatting.IsCode	boolean	Genellikle çok satırlı girişlerle kod için giriş alanını biçimlendirer. Standart yazı tipi yerine kod benzeri bir yazı tipi kullanır.

Temel örnek

Aşağıdaki kod parçacığı (ve sonuçta elde edilen iletişim kutuları) HelloWorldWithDocs örneğinden alınmalıdır.

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

Bu kod, Power BI'da aşağıdaki iletişim kutularına neden olur.

İşlev çağırma

İşlev bilgileri

Çok satırlı örnek

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

Bu kod (ilişkili yayımlama bilgileriyle vb.) Power BI'da aşağıdaki iletişim kutusuna neden olur. Yeni satırlar metinde '#(lf)' veya 'satır akışı' ile gösterilir.