Udostępnij za pośrednictwem

TripPin — część 8 — dodawanie diagnostyki

  • Artykuł

Uwaga

Ta zawartość odwołuje się obecnie do zawartości ze starszej implementacji diagnostyki w programie Visual Studio. Zawartość zostanie zaktualizowana w najbliższej przyszłości, aby uwzględnić nowy zestaw POWER Query SDK w programie Visual Studio Code.

Ten wieloczęściowy samouczek obejmuje tworzenie nowego rozszerzenia źródła danych dla dodatku Power Query. Samouczek ma być wykonywany sekwencyjnie — każda lekcja opiera się na łączniku utworzonym w poprzednich lekcjach, przyrostowo dodając nowe możliwości do łącznika.

W tej lekcji wykonasz następujące lekcji:

  • Dowiedz się więcej o funkcji Diagnostics.Trace
  • Używanie funkcji pomocnika diagnostyki do dodawania informacji śledzenia w celu ułatwienia debugowania łącznika

Włączanie diagnostyki

Użytkownicy dodatku Power Query mogą włączyć rejestrowanie śledzenia, zaznaczając pole wyboru w obszarze Opcje | Diagnostyka.

Włącz śledzenie w dodatku Power Query.

Po włączeniu wszystkie kolejne zapytania spowodują, że aparat M będzie emitować informacje śledzenia do plików dziennika znajdujących się w stałym katalogu użytkownika.

W przypadku uruchamiania zapytań języka M z poziomu zestawu SDK dodatku Power Query śledzenie jest włączone na poziomie projektu. Na stronie właściwości projektu istnieją trzy ustawienia związane z śledzeniem:

  • Wyczyść dziennik — po ustawieniu truewartości dziennik zostanie zresetowany/wyczyszczone podczas uruchamiania zapytań. Zalecamy zachowanie tego ustawienia na wartość true.
  • Pokaż ślady aparatu — to ustawienie steruje danymi wyjściowymi wbudowanych śladów z aparatu M. Te ślady są przydatne tylko dla członków zespołu Dodatku Power Query, więc zazwyczaj chcesz zachować ten zestaw na wartość false.
  • Pokaż ślady użytkownika — to ustawienie steruje danymi wyjściowymi śledzenia danych wyjściowych łącznika. Należy ustawić tę wartość na true.

Właściwości projektu.

Po włączeniu tej opcji zobaczysz wpisy dziennika w oknie Dane wyjściowe zapytania języka M na karcie Dziennik.

Diagnostics.Trace

Funkcja Diagnostics.Trace służy do zapisywania komunikatów w dzienniku śledzenia aparatu M.

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

Ważne

M to język funkcjonalny z leniwą oceną. W przypadku używania Diagnostics.Tracefunkcji należy pamiętać, że funkcja będzie wywoływana tylko wtedy, gdy wyrażenie jest częścią, jest faktycznie obliczane. Przykłady tego samouczka można znaleźć w dalszej części tego samouczka.

Parametr traceLevel może być jedną z następujących wartości (w kolejności malejącej):

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

Po włączeniu śledzenia użytkownik może wybrać maksymalny poziom komunikatów, które mają zobaczyć. Wszystkie komunikaty śledzenia tego poziomu i w obszarze będą zwracane do dziennika. Jeśli na przykład użytkownik wybierze poziom "Ostrzeżenie", w dziennikach będą wyświetlane komunikaty TraceLevel.Warningśledzenia , TraceLevel.Errori TraceLevel.Critical .

Parametr message jest rzeczywistym tekstem, który będzie wyjściowy do pliku śledzenia. Tekst nie będzie zawierać parametru value , chyba że jawnie dołączysz go do tekstu.

Parametr value jest tym, co funkcja zwróci. delayed Gdy parametr jest ustawiony na truewartość , value będzie to funkcja zerowego parametru, która zwraca wartość rzeczywistą, którą oceniasz. Gdy delayed parametr ma wartość false, value będzie wartością rzeczywistą. Przykład tego działania można znaleźć poniżej.

Korzystanie z diagnostyki. Śledzenie w łączniku TripPin

Aby uzyskać praktyczny przykład użycia pliku Diagnostics.Trace i wpływu delayed parametru, zaktualizuj funkcję łącznika GetSchemaForEntity TripPin, aby opakowować error wyjątek:

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

Możesz wymusić błąd podczas oceny (dla celów testowych!), przekazując nieprawidłową nazwę jednostki do GetEntity funkcji. W tym miejscu zmienisz withData wiersz w TripPinNavTable funkcji, zastępując element [Name] "DoesNotExist".

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;

Włącz śledzenie projektu i uruchom zapytania testowe. Errors Na karcie powinien zostać wyświetlony tekst zgłoszonego błędu:

Komunikat o błędzie.

Ponadto na Log karcie powinien zostać wyświetlony ten sam komunikat. Jeśli używasz różnych wartości dla parametrów message i value , będą one inne.

Dziennik błędów.

Należy również pamiętać, że Action pole komunikatu dziennika zawiera nazwę (rodzaj źródła danych) rozszerzenia (w tym przypadku Engine/Extension/TripPin). Ułatwia to znajdowanie komunikatów związanych z rozszerzeniem w przypadku włączenia wielu zapytań i/lub śledzenia systemu (aparatu mashupu).

Opóźniona ocena

Jako przykład działania parametru delayed wprowadzisz pewne modyfikacje i ponownie uruchomisz zapytania.

Najpierw ustaw delayed wartość falsena , ale pozostaw value parametr w następujący sposób:

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

Po uruchomieniu zapytania zostanie wyświetlony błąd "Nie możemy przekonwertować wartości typu Funkcja na typ" i nie zostanie zgłoszony rzeczywisty błąd. Jest to spowodowane tym, że wywołanie zwraca function teraz wartość, a nie samą wartość.

Następnie usuń funkcję z parametru value :

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

Po uruchomieniu zapytania zostanie wyświetlony prawidłowy błąd, ale jeśli sprawdzisz kartę Dziennik , nie będzie żadnych komunikatów. Jest to spowodowane tym, że wynik error jest zgłaszany/oceniany podczas wywołania metody Diagnostics.Trace, więc komunikat nigdy nie jest rzeczywiście zwracany.

Teraz, gdy rozumiesz wpływ parametru delayed , pamiętaj, aby zresetować łącznik z powrotem do stanu roboczego przed kontynuowaniem.

Funkcje pomocnika diagnostycznego w pliku Diagnostics.pqm

Plik Diagnostics.pqm zawarty w tym projekcie zawiera wiele funkcji pomocnika, które ułatwiają śledzenie. Jak pokazano w poprzednim samouczku, możesz dołączyć ten plik do projektu (pamiętając o ustawieniu akcji kompilacji na kompilowanie), a następnie załadować go w pliku łącznika. Dolna część pliku łącznika powinna teraz wyglądać podobnie do poniższego fragmentu kodu. Możesz zapoznać się z różnymi funkcjami dostępnymi w tym module, ale w tym przykładzie będziesz używać Diagnostics.LogValue tylko funkcji i 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

Funkcja Diagnostics.LogValue jest bardzo podobna Diagnostics.Tracedo funkcji i może służyć do wyprowadzania wartości ocenianej wartości.

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

Parametr prefix jest poprzedzany komunikatem dziennika. Użyjesz tego polecenia, aby ustalić, które wywołanie danych wyjściowych komunikatu. Parametr value jest tym, co funkcja zwróci, a także zostanie zapisana w śladzie jako tekstowa reprezentacja wartości języka M. Jeśli na przykład value wartość jest równa kolumnom table A i B, dziennik będzie zawierać równoważną #table reprezentację: #table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

Uwaga

Serializowanie wartości M do tekstu może być kosztowną operacją. Należy pamiętać o potencjalnym rozmiarze wartości, które są zwracane do śledzenia.

Uwaga

Większość środowisk Dodatku Power Query obcina komunikaty śledzenia do maksymalnej długości.

Na przykład zaktualizujesz TripPin.Feed funkcję w celu śledzenia url argumentów i schema przekazanych do funkcji .

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;

Musisz użyć nowych _url wartości i _schema w wywołaniu metody GetAllPagesByNextLink. Jeśli użyto oryginalnych parametrów funkcji, Diagnostics.LogValue wywołania nigdy nie zostaną ocenione, co nie spowoduje zapisania komunikatów do śledzenia. Programowanie funkcjonalne jest zabawne!

Po uruchomieniu zapytań w dzienniku powinny zostać wyświetlone nowe komunikaty.

Uzyskiwanie dostępu do adresu URL:

Uzyskiwanie dostępu do komunikatu adresu URL.

Typ schematu:

Komunikat typu schematu.

Zobaczysz serializowaną wersję parametru schema type, a nie to, co otrzymasz, gdy wykonasz proste Text.FromValue w wartości typu (co powoduje "typ").

Diagnostics.LogFailure

Funkcja Diagnostics.LogFailure może służyć do zawijania wywołań funkcji i będzie zapisywać tylko do śledzenia, jeśli wywołanie funkcji zakończy się niepowodzeniem (oznacza to, że zwraca wartość error).

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

Diagnostics.LogFailure Wewnętrznie dodaje try operator do wywołaniafunction. Jeśli wywołanie zakończy się niepowodzeniem, text wartość zostanie zapisana w śladzie przed zwróceniem oryginalnego errorelementu . Jeśli wywołanie function powiedzie się, wynik zostanie zwrócony bez konieczności pisania niczego do śledzenia. Ponieważ błędy języka M nie zawierają pełnego śledzenia stosu (oznacza to, że zazwyczaj jest wyświetlany tylko komunikat o błędzie), może to być przydatne, gdy chcesz wskazać, gdzie został zgłoszony błąd.

Jako przykład (słaby) zmodyfikuj withData wiersz TripPinNavTable funkcji, aby ponownie wymusić błąd:

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

W śladzie można znaleźć wynikowy komunikat o błędzie zawierający textelement i oryginalne informacje o błędzie.

Komunikat LogFailure.

Przed przejściem do następnego samouczka pamiętaj, aby zresetować funkcję do stanu roboczego.

Podsumowanie

W tej krótkiej lekcji (ale ważne!) pokazano, jak używać funkcji pomocnika diagnostycznego do rejestrowania się w plikach śledzenia dodatku Power Query. Gdy te funkcje są używane prawidłowo, są przydatne podczas debugowania problemów w łączniku.

Uwaga

Jako deweloper łącznika ponosisz odpowiedzialność za to, aby w ramach rejestrowania diagnostycznego nie rejestrować poufnych ani danych osobowych. Należy również zachować ostrożność, aby nie zwracać zbyt dużej ilości informacji śledzenia, ponieważ może to mieć negatywny wpływ na wydajność.

Następne kroki

TripPin — część 9 — test Połączenie ion