TripPin 第 8 部分 - 新增診斷

發行項
05/22/2024

注意

此內容目前會參考 Visual Studio 中診斷舊版實作的內容。內容將於近期更新，以涵蓋 Visual Studio Code 中的新 Power Query SDK。

此多部分教學課程涵蓋如何建立Power Query的新數據源延伸模組。本教學課程旨在循序完成，每個課程都是以先前課程中建立的連接器為基礎，以累加方式將新功能新增至您的連接器。

在本課程中，您將會：

瞭解 Diagnostics.Trace 函式
使用診斷協助程式函式來新增追蹤資訊以協助偵錯連接器

啟用診斷

Power Query 用戶可以選取 [選項] 底下的 複選框來啟用追蹤記錄 |診斷。

在 Power Query 中啟用追蹤。

啟用之後，任何後續查詢都會造成 M 引擎發出追蹤資訊至位於固定使用者目錄中的記錄檔。

從 Power Query SDK 內執行 M 查詢時，會在專案層級啟用追蹤。在 [項目屬性] 頁面上，有三個與追蹤相關的設定：

清除記錄檔 -- 當此設定為 true時，當您執行查詢時，將會重設/清除記錄檔。建議您將這個設定保留為 true。
顯示引擎追蹤 - 此設定可控制 M 引擎內建追蹤的輸出。這些追蹤僅適用於 Power Query 小組的成員，因此您通常會想要將此設定保留為 false。
顯示使用者追蹤- 此設定可控制連接器所輸出的追蹤資訊。您要將這個設定為 true。

項目屬性。

啟用之後，您就會開始在 [記錄] 索引標籤下的 [M 查詢輸出] 視窗中看到記錄專案。

Diagnostics.Trace

Diagnostics.Trace 函式可用來將訊息寫入 M 引擎的追蹤記錄檔。

Diagnostics.Trace = (traceLevel as number, message as text, value as any, optional delayed as nullable logical as any) => ...

重要

M 是一種功能語言，具有延遲評估。使用 Diagnostics.Trace時，請記住，只有在實際評估其所屬的表達式時，才會呼叫函式。本教學課程稍後可以找到此範例。

參數 traceLevel 可以是下列其中一個值（以遞減順序）：

TraceLevel.Critical
TraceLevel.Error
TraceLevel.Warning
TraceLevel.Information
TraceLevel.Verbose

啟用追蹤時，用戶可以選取他們想要查看的訊息層級上限。此層級和下方的所有追蹤訊息都會輸出至記錄檔。例如，如果使用者選取 [警告] 層級，則會在記錄中顯示、 TraceLevel.Error和 TraceLevel.Critical 的TraceLevel.Warning追蹤訊息。

參數 message 是將輸出至追蹤檔案的實際文字。除非您明確將它包含在文字中，否則文字不會包含 value 參數。

參數 value 是函式將傳回的內容。 delayed當參數設定為 true時，value會是零個參數函式，會傳回您正在評估的實際值。當設定為 falsevalue 時delayed，將會是實際值。您可以在下方找到其運作方式的範例。

使用診斷。 TripPin 連接器中的追蹤

如需使用 Diagnostics.Trace 和參數影響 delayed 的實際範例，請更新 TripPin 連接器的 GetSchemaForEntity 函式來包裝 error 例外狀況：

GetSchemaForEntity = (entity as text) as type =>
    try
        SchemaTable{[Entity=entity]}[Type]
    otherwise
        let
            message = Text.Format("Couldn't find entity: '#{0}'", {entity})
        in
            Diagnostics.Trace(TraceLevel.Error, message, () => error message, true);

您可以將無效的實體名稱傳遞至 GetEntity 函式，以強制評估期間發生錯誤。。在這裡，您會變更 withData 函式中的TripPinNavTable行，並將取代為 "DoesNotExist"[Name] 。

TripPinNavTable = (url as text) as table =>
    let
        // Use our schema table as the source of top level items in the navigation tree
        entities = Table.SelectColumns(SchemaTable, {"Entity"}),
        rename = Table.RenameColumns(entities, {{"Entity", "Name"}}),
        // Add Data as a calculated column
        withData = Table.AddColumn(rename, "Data", each GetEntity(url, "DoesNotExist"), type table),
        // Add ItemKind and ItemName as fixed text values
        withItemKind = Table.AddColumn(withData, "ItemKind", each "Table", type text),
        withItemName = Table.AddColumn(withItemKind, "ItemName", each "Table", type text),
        // Indicate that the node should not be expandable
        withIsLeaf = Table.AddColumn(withItemName, "IsLeaf", each true, type logical),
        // Generate the nav table
        navTable = Table.ToNavigationTable(withIsLeaf, {"Name"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        navTable;

啟用項目的追蹤，並執行測試查詢。在索引 Errors 標籤上，您應該會看到您引發之錯誤的文字：

錯誤訊息。

此外，在索引標籤上 Log ，您應該會看到相同的訊息。如果您針對 message 和 value 參數使用不同的值，則這些值會不同。

錯誤記錄檔。

另請注意， Action 記錄訊息的欄位包含延伸模組的名稱（資料來源種類），在此案例中為 Engine/Extension/TripPin。這可讓您在涉及多個查詢和/或系統（混搭引擎）追蹤時，更輕鬆地尋找與延伸模組相關的訊息。

延遲評估

作為參數運作方式 delayed 的範例，您將進行一些修改，然後再次執行查詢。

首先，將 delayed 值設定為 false，但將 value 參數保留為：

Diagnostics.Trace(TraceLevel.Error, message, () => error message, false);

當您執行查詢時，會收到「我們無法將 Function 類型的值轉換成類型類型」的錯誤，而不是您引發的實際錯誤。這是因為呼叫現在會傳 function 回值，而不是值本身。

接下來，從 value 參數中移除函式：

Diagnostics.Trace(TraceLevel.Error, message, error message, false);

當您執行查詢時，會收到正確的錯誤，但如果您核 取 [記錄 ] 索引標籤，就不會有訊息。這是因為 error 最後會在呼叫 Diagnostics.Trace期間引發/評估 ，因此訊息永遠不會實際輸出。

既然您已了解參數的影響 delayed ，請務必先將連接器重設為工作狀態，再繼續進行。

Diagnostics.pqm 中的診斷協助程式函式

此專案中包含的 Diagnostics.pqm 檔案包含許多協助程式函式，可讓追蹤變得更容易。如上一個教學課程所示，您可以在專案中包含此檔案（記得將建置動作設定為編譯），然後在連接器檔案中載入它。連接器檔案底部現在看起來應該類似下面的代碼段。您可以隨意探索本課程模組所提供的各種函式，但在此範例中，您只會使用 Diagnostics.LogValue 和 Diagnostics.LogFailure 函式。

// Diagnostics module contains multiple functions. We can take the ones we need.
Diagnostics = Extension.LoadFunction("Diagnostics.pqm");
Diagnostics.LogValue = Diagnostics[LogValue];
Diagnostics.LogFailure = Diagnostics[LogFailure];

Diagnostics.LogValue

函 Diagnostics.LogValue 式非常類似 Diagnostics.Trace，可用來輸出您正在評估的值。

Diagnostics.LogValue = (prefix as text, value as any) as any => ...

參數 prefix 會前面加上記錄訊息。您會使用此項目來找出哪一個呼叫輸出訊息。參數是函 value 式將傳回的內容，也會寫入追蹤做為 M 值的文字表示。例如，如果 value 等於 table 具有數據行 A 和 B 的，則記錄檔會包含對等 #table 表示法： #table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

注意

將 M 值串行化為文字可能是一項昂貴的作業。請注意您要輸出至追蹤的值可能大小。

注意

大部分的Power Query環境會將追蹤訊息截斷為最大長度。

例如，您將更新函 TripPin.Feed 式，以追蹤 url 傳入函式的和 schema 自變數。

TripPin.Feed = (url as text, optional schema as type) as table =>
    let
        _url = Diagnostics.LogValue("Accessing url", url),
        _schema = Diagnostics.LogValue("Schema type", schema),
        //result = GetAllPagesByNextLink(url, schema)
        result = GetAllPagesByNextLink(_url, _schema)
    in
        result;

您必須在呼叫 GetAllPagesByNextLink中使用新的 _url 和 _schema 值。如果您使用原始函式參數， Diagnostics.LogValue 則永遠不會實際評估呼叫，因此不會產生寫入追蹤的訊息。 功能程序設計很有趣！

當您執行查詢時，現在應該會在記錄中看到新的訊息。

存取 URL：

存取 URL 訊息。

架構類型：

架構類型訊息。

您會看到參數type的schema串行化版本，而不是您在類型值上執行簡單Text.FromValue作業時得到的內容（這會導致「類型」）。

Diagnostics.LogFailure

函Diagnostics.LogFailure式可以用來包裝函數調用，而且只有在函式呼叫失敗時才會寫入追蹤（也就是傳回。error

Diagnostics.LogFailure = (text as text, function as function) as any => ...

在內部， Diagnostics.LogFailure 將運算元新增 try 至 function 呼叫。如果呼叫失敗，則會 text 先將值寫入追蹤，再傳回原始 error。 function如果呼叫成功，則會傳回結果，而不會將任何專案寫入追蹤。由於 M 錯誤不包含完整的堆疊追蹤（也就是說，您通常只會看到錯誤的訊息），因此當您想要找出錯誤引發的位置時，這非常有用。

例如，修改函 withData 式行 TripPinNavTable 以再次強制錯誤：

withData = Table.AddColumn(rename, "Data", each Diagnostics.LogFailure("Error in GetEntity", () => GetEntity(url, "DoesNotExist")), type table),

在追蹤中，您可以找到包含、 text和原始錯誤資訊的結果錯誤訊息。

LogFailure 訊息。

在繼續進行下一個教學課程之前，請務必將函式重設為工作狀態。

結論

這個簡短的（但重要！）課程示範如何使用診斷協助程式函式來記錄至 Power Query 追蹤檔案。正確使用時，這些函式有助於偵錯連接器內的問題。

注意

身為連接器開發人員，您必須負責確保您不會將敏感性或個人標識資訊（PII）記錄為診斷記錄的一部分。您也必須小心不要輸出太多追蹤信息，因為它可能會對效能造成負面影響。

下一步

TripPin 第 9 部分 - 測試連線 ion

共用方式為