Home    Firma    Produkty    Kontakt    Logowanie   

Pierwsze kroki z konektorem XFuture

 

Za pomocą konektorów bankowych XFuture możesz skutecznie zarządzać swoimi środkami finansowymi na wybranym rachunku bankowym. W tym dokumencie staramy się pokazać Ci, jak wykonać podstawowe operacje oraz jak wygląda metodologia pracy z biblioteką. Zanim przystapisz do lektury, powinieneś posiadać wstępną wiedzę na temat zasady działania konektora, dlatego jeśli nie przeczytałeś publikacji poświęconej wprowadzeniu do użytkowania konektorów bankowych XFuture, sugerujemy abyś zrobił to zanim przejdziesz do dalszej części tego dokumentu. Wspomniany artykuł znajdziesz na stronie WWW wybranego konektora .


 

   Aby wykorzystać możliwości wybranego konektora bankowego i zbudować szkielet aplikacji, która wdraża to rozwiązanie, będziesz potrzebował minimum wiedzy programistycznej i maksymalnie piętnaście minut wolnego czasu. Chociaż wydaje się to niewiarygodne, biblioteka została zbudowana w taki sposób, aby każdy, niezaleznie od tego, czy jest zawodowym programistą, czy też zajmuje się technlogiami IT niezobowiązująco, mógł przy minimalnym wysiłku i w krótkim czasie osiągnąc zadowalający efekt końcowy. Zamierzam pokazać Ci, jak to zrobić, dlatego przygotuj sobie gorącą kawę lub herbatę, a ja gwarantuję Ci, że zanim zdąży wystygnąć, będziesz miał u siebie program, który za pomocą biblioteki konektora podłącza się do Twojego banku i otwiera przed Tobą nowe możliwości zarządzania środkami finansowymi.
   Zanim zaczniemy, chcę Cię poprosić, abyś pobrał ze strony konektora bankowego wydanie LITE biblioteki. Pobierz również dokumentację techniczną, jeśli jeszcze tego nie zrobiłeś. Wszystkie czynności, które będe opisywał, wykonuję w środowisku autorskim Microsoft VisualStudio 2008, niemniej jeśli posiadasz inną wersję tego narzędzia, nie musisz się przejmować. Prawdopodobnie większość czynności da się u Ciebie wykonać w sposób analogiczny i nie będziesz miał z tym żadnych problemów. Dla celów pokazowych wykorzystuję również wydanie LITE zestawu konektora dla mBanku, ale jeśli interesuje Cię zastosowanie konektora do innego banku, treści zawarte tutaj są wciąż aktualne, ponieważ wszystki konektory działają analogicznie. Demonstrując przykłady wykorzystuję język C#. Jeśli programujesz w innym języku platformy .NET, większość informacji zawartych tutaj jest dla Ciebie wiążaca,  ale pewne detale implementacji będą w Twoim języku wyglądały inaczej. Musisz te sytuacje rozpoznać i uwzględnić je bazując na swoim doświadczeniu.
   Ok, Zakładam, że pobrałeś już wszystkie zasoby, o które prosiłem, dlatego rozpocznijmy naszą zabawę. Utwórz nowy projekt C# według szablonu ‘Windows Forms Application’. VisualStudio (VS) wygeneruje dla Ciebie szkielet aplikacji z pojedynczą formatką. Dla naszego demonstracyjnego programu będzie to jedyne okienko, jakie będzie posiadała aplikacja. Celowo staram się przedstawić tu prostą konstrukcję tak, aby ułatwić Ci namacalne doświadczenie tego, jak powinno działać rozwiązanie bazujące na konektorze. W naszej aplikacji ograniczymy się do utworzenia panelu, który umożliwi zalogowanie do konta, oraz pobierze informacje na temat dostępnych rachunków. Oczywiście możliwości konektora, nawet w wydaniu LITE, są o wiele większe. Uważam jednak, że do demonstracji idei, wystarczy nam zaimplementowanie tej prostej funkcjonalności. Dzieki temu będziemy mieli minimum kodu, a przy tym uda się uchwycić ogólną koncepcję architektoniczną, obowiązujacą przy wdrażaniu pozostałych funkcjonalności konektora.  Chcę abyś przez cały czas miał świadomość, że konektor realizuje proste czynności i jest łatwy w obsłudze. Postaram się pokazać Ci bez zbędnego owijania w bawełnę jak działa i co potrafi tak, abyś mógł za jego pomocą zrealizoać cokolwiek wymyślisz. Oczywiscie o ile mieści się to w temacie sterowania finansami.
   Skoro wyjaśniliśmy sobie założenia, przejdźmy do praktycznej realizacji. Na rysunku 1 przedstawiono docelowy interfejs użytkownika. image002Chcę Cię teraz poprosić, abyś po utworzeniu projektu, doprowadził główne okno aplikacji do podobnego stanu (nie zapomnij również dodać do projektu referencji do biblioteki dll konetkora ).  Jak widzisz mamy tutaj cztery komponenty tekstowe i jeden przycisk. Chcę, abyś nadał tym kontrolkom odpowiednie nazwy: dla kontrolki przeznaczonej na hasło – textBoxHaslo ; dla kontrolki  login – textBoxLogin ; dla kontrolki stanu konektora – textBoxStanKonektora oraz dla kontrolki rachunków – textBoxRachunki. Te nazwy są istotne, ponieważ będziemy się do nich odwoływali w kodzie dokładnie przez ich nazwy instancji. Co będzie robił nasz program? Jak zapewne wnioskujesz z wyglądu okienka, pozwoli on wprowadzić login i hasło, a następnie kliknąć przycisk ‘Zaloguj’. Przycisk ten wywoła metodę ‘login’. Jeśli czytałeś wstęp do użytkowania konektorów, to wiesz już zapewne, że usługi konektora są asynchroniczne. Nasza aplikacja zarejestruje słuchaczy kluczowych zdarzeń dla obsługiwanej funkcjonalności. Otwórz proszę dokumentację na stronie ze wsparciem dla metody ‘login’. Jak widzisz metoda login jest bezargumentowa, nas jednak interesuje to, jakie zdarzenia może generować. Każda usługa generuje jakiś zestaw zdarzeń i dokumentacja pozwoli Ci ustalić, które z nich powinieneś obsłużyć.  
   Przy wywołaniu usługi asynchroznicznej ( a taką jest usługa ‘login’ ), sterowanie natychmiast (jeszcze przed zakończeniem usługi) wraca do punktu wywołania. Oznacza to, że rezultatów wywołania powinniśmy spodziewać się gdzie indziej  i tym miejscem jest słuchacz zdarzenia ‘OperationFinished’. Usługa wyzwala to zdarzenie aby poinformować o zakończeniu operacji, niezależnie od tego, czy operacja się powiodła, czy też nie. Dodatkowo metoda ‘login’ generuje zdarzenia ‘statusChanged’ . To zdarzenie wyzwalane jest, gdy zmienia się stan wykonywanej operacji i jest pomocne przy monitorowaniu postępu.
   Wiemy już czego się spodziewać po wywołaniu, dlatego zacznijmy budowa ć serce aplikacji. Kliknij gdzieś w obszarze formy, aby przenieść się do kodu klasy formatki. Obiekt formatki two rzony jest przy starcie programu i, jeśli nie wykonasz dziwnych,  niestandardowych działań, będzie istniał przez cały czas życia aplikacji. To doskonała wiadomość,  ponieważ klasa formatki nadaje się, aby zdeklarować w niej nową istancję konektora. Tak też uczynimy. Zaraz  za nawiasem otwierającym ciało klasy formatki dopisz deklarację referencji do obiektu klasy konektora .  Zwróć uwagę, że nie tworzymy tu jeszcze obiektu. Konstruktor klasy konektora wymagaimage005 podania argumentów, a ich wartości na tym etapie nie znamy. Jeśli masz wątpliwości jakie to argumenty, znajdź w dokumentacji fragment poświęcony konstruktorowi. Jak widzisz trzeba do niego przekazać login i hasło. Te wartości  poznamy, gdy użytkownik kliknie przycisk logowania, dlatego dopiero w ciele obsługi z darzenia kliknięcia tego przycisku stworzymy obiekt konektora i przypiszemy go do referencji, którą zdefiniowaliśmy jako składową klasy formatki. Uczynimy to w kolejnym kroku i proponuję, abyśmy wykonali go teraz. Kliknij dwa razy w przycisk logowania tak, aby środowisko utworzyło subskrybenta zdarzenia kliknięcia. W kodzie tego słuchacza powinna znaleźć się zawartość taka, jak na rysunku 4. Po pierwsze mamy tam warunek sprawdzający, czy wymagane pola zostały wypełnione. To nie wymaga komentarza. To, co istotne z naszego punktu widzenia, znajduje się w ciele warunku testującego referencję konektora. Jeśli nie utworzono jeszcze instancji klasy konektora (==null ), to jest ona tworzona w oparciu o dane z pól formularza. Do konstruktora przkazywany jest login i hasło. Następnie dodawane są subskrypcje do zdarzeń. Visual Studio w znakomity sposób wspiera tworzenie i dodawanie słuchaczy zdarzeń. Jeśli próbujesz użyć operatora += na instancji zdarzenia, środowisko zaproponuje Ci automatycznie utworzenie kodu delegacji, a jeśli się zgodzisz ( wciskając TAB ), utworzy dla Ciebie również implementację słuchacza. Myślę, że to jest jeden z tych momentów, w których wiesz za co zapłaciłeś wykupując swoją licencję na Visual Studio. Jeśli pozwolisz środowisku VS utworzyć słuchaczy za Ciebie, Twój kod będzie wyglądał tak jak na rysunku 4. Nie musisz wtedy martwić się o to, jaką postać powinien mieć słuchacz, ponieważ całą sprawą zajmie się środowisko. Warto wspomnieć, że deweloperzy z Microsoft to na tyle mili ludzie, że przeciążyli operator += klasy delegacji w bardzo przyjemny sposób i jeśli nie tworzysz słuchaczy automatycznie ( tzn. jesteś miłośnikeim ręcznej roboty ), wystarczy że po prawej stronie operatora podasz nazwę metody słuchacza, a instancja delegacji ( jeśli sygnatura słuchacza jest zgodna z prototypem wyrażonym przez definicję delegacji ) będzie tworzona domyślnie poza kulisami. Definitywnie zwiększa to czytelność kodu i gdyby zastosować to w naszym kodzie, to wyrażenie tworzące delegację, tj. new Gtools.mBankConncector.mBankOperation[...] , zastąpilibyśmy po prostu nazwą słuchacza ( w tym przypadku tym, co znajduje się w nawiasach konstruktora delegacji ). Ja skorzystałem ze wsparcia VS i pozwoliłem mu wygenerować kod. Zrobiłem to dlatego, poniważ jestem leniwy, oraz dlatego, aby jasno było widać jakiego typu delegatem musi być słuchacz.
   Dodaliśmy więc obsługę dwóch zdarzeń. Przyszedł czas, aby zająć się ich słuchaczami. Ponieważ spotkało nas wielkie szczęście i środowisko utworzyło juz odpowiednie metody grające role słuchaczy, przenieśmy się do nich i wpiszmy tam kilka rzeczy. Na początek proponuję zająć się metodą mBank_operationFinished. Zwróć przy okazji uwagę, jakie nazewnictwo zaproponowało środowisko dla metod obsługi zdarzeń; nazwa składa się z członu identyfikującego nazwę instancji klasy, która generuje zdarzenie, oraz z nazwy zdarzenia. Taka czytelność niezmiernie mnie cieszy i Ciebie również powinna, jeśli weźmiesz pod uwagę, że to ułatwi Ci życie gdy Twój program rozrośnie się do monstrualnych rozmiarów, a Ty z jakichś irracjonalnych powodów nie zbudujesz go modułowo i skumulujesz kod w jednym miejscu. Wróćmy jednak do naszego słuchacza. Definicję odpowiedniej metody przedstawiliśmy na rysunku 5; u Ciebie powinno to wyglądać tak samo. W tym momencie jestem Ci winien dwa słowa wyjaśnienia na temat tego, co dzieje się w słuchaczu z rysunku 5. Przede wszystkim słuchacz wywoływany jest z argumentem, definiującym stan zakończonej operacji. Ten stan reprezentowany jest przez typ enumeratywny wyliczający dwie wartości: SUCCES oraz FAILURE. Nie będę tego komentował, dodam jedynie, że jeśli coś poszłoby nie tak, to sygnatura błędu dostępna jest za pomocą właściwości errorMessage klasy konektora. image004
Musisz wiedzieć, że operacja asynchroniczna wykonywana jest w równoległym wątku. W czasach, w których powstaje ten dokument, główny wątek aplikacji Windows Forms, odpowiadający za  interfejs użytkownika, pracuje według modelu, który specjaliści nazywają STA (Single Thread Apartment). Ten model nie dopuszcza, aby kod wykonywany w wątku X uzyskiwał bezpośredni dostęp do zasobów zadeklarowanych i utworzonych w wątku Y. Kiedy usługa konektora generuje zdarzenie, wywołuje zwrotnie słuchacza tego zdarzenia i wykonuje jego kod w kontekście własnego wątku. Dlatego jeśli z poziomu słuchacza spróbujesz usyskać dostęp np do właściwości text wybranego pola tekstowego formatki, to .NET wygeneruje wyjątek. Dlaczego? Poniważ  kod słuchacza wykonuje się w wątku asynchronicznej usługi konektora, a wszystkie elementy interfejsu są ‘własnością’ wątku głównego. Aby sprostać wyzwaniu, musimy sprawdzić, czy trzeba ponownie uruchomić słuchacza, tym razem w wątku głównym, i jeśli zachodzi taka potrzeba, zrobić to. Za to zadanie odpowiedzialne są instrukcje związane z InvokeRequired oraz BeginInvoke. Nie będę tego dokładnie omawiał, ponieważ te kwestie są doskonale opisane w wielu miejscach w internecie i jeśli czujesz potrzebę zgłębienia tematu, nie będę Cię powstrzymywał.
    Jeśli kod słuchacza wykonywany jest w odpowiednim wątku, następuje wykonanie bloku ‘else’. W tym fragmencie sprawdzana jest przyczyna zakończenia operacji. Jeśli coś poszło nie tak, wyświetlany jest monit, jeśli natomiast operacja się udała, wyliczaczne są wszystkie zgromadzone rachunki, a podstawowe informacje o nich drukowane są do odpowiedniego pola tekstowego. Metoda tego słuchacza nie robi nic więcej.
Pochylmy się teraz nad wnętrznościami słuchacza zdarzenia zmiany statusu. Ciało tego słuchacza zostało dla nas utworzone przez środowisko podczas subskrybowania zdarzenia i jego nazwa to mBank_statusChanged. Podczas wykonywania operacji logowania, status konektora ulega kilkukrotnie zmianie, informując o aktualnym stanie operacji. Nie musisz tego zdarzenia obsługiwać, ale czasem dobrze jest wiedzieć  co się dzieje. Spójrzmy jaki kod proponujemy tam wszczepić i jak to działa.  Na rysunku 6image008 znajduje się listing, o którym mowa. Jak widzisz znajduje się tam blok warunkowy dbający o spełnienie wymagań modelu STA, a gdy nie ma przeciwwskazań, do właściwego pola tekstowego drukowana jest informacja o nowym stanie konektora. I tyle. Jak widzisz wszystko jest proste, ładne i przyjemne. Jeśli postępowałeś zgodnie ze wskazówkami, możesz teraz uruchomić aplikację. Mam nadzieję, że zgodnie z sugestią zrobiłeś sobie na początku kawę. Jeśli tak, teraz jest dobry moment, żeby ją wypić zanim całkiem wystygnie.
Uruchamiamy aplikację, podajemy login i hasło, klikamy przycisk ‘Zaloguj’ i ... [ w tle słychać oklaski, publiczność szaleje ]. Zrobiłeś to ! Muszę Ci pogratulować, bo właśnie ujarzmiłeś pełne ‘mocy’ rozwiązanie do wspomagania gospodarki finansowej, najlepsze jakie dostępne jest w Polsce na rynku dla deweloperów .NET. Chcę abyś miał świadomość, że stało się coś ważnego. Z wagi tego czynu zdasz sobie sprawę, kiedy po wdrożeniu konektora do systemu finansowego firmy, zadowolenie klientów wzrośnie, przychody wzrosną, ilość wymaganej do wykonania pracy spadnie i będzie można wysłać na emeryturę kilku leniwych pracowników księgowości, którzy po pojawieniu się konektora XFuture opanowali gadu-gadu, pasjansja oraz sapera do perfekcji.

   Nasza aplikacja szczęśliwie działa, ale nie powiedzieliśmy sobie nic na temat bezpieczeństwa, ani nie zrobiliśmy nic w celu jego zapewnienia. Jako programiści nie musimy nic robić, ponieważ biblioteka konektora jest bardzo restrykcyjna, i w razie wystąpnienia problemów z podpisem klucza publicznego, zgłosi błąd w zdarzeniu ‘OperationFinished’ już na etapie nawiązywania połączenia. Komunikat błędu dostępny za pomocą właściwości errorMessage klasy konektora może w tym wypadku nie być wiążący i sugerować problem z uzyskaniem danych, nie wspominając nic o kwesti naruszenia zasad bezpieczeństwa. Dlatego aby prawidłowo obsłużyć kwestie związane z walidacją certyfikatów SSL, powinieneś dołączyć  subskrypcję zdarzenia SSLPolicyError. Wystąpienie tego zdarzenia daje Ci unikalną szansę identyfikacji sytuacji, kiedy masz doczynieina z próba wyłudzenia danych, albo wykrycia, że w torze połączenia pracuje serwer proxy.  Ten serwer może być szpiegowski, albo diagnostyczny, albo być tam z innego powodu. W każdym z tych przypadków powinieneś podjąć działania w oparciu o Twoją świadomość sytuacji i uwarunkowania infrastruktury firmowej. Nie będziemy tutaj demonstrowali implementacji słuchacza tego zdarzenia, ponieważ obsługuje się je tak samo, jak każde inne zdarzenie i wierzę, że w oparciu o to, co już powiedziano, będziesz w stanie zbudować wsparcie dla pozostałych funkcjonalności konektora. Pragnę jedynie dodać, że aby sprawdzić, czy to zdarzenie działa, możesz postawić lokalnie serwer proxy ( np jeden z debuggerów http ) i zezwolić mu na tunelowanie połączeń https (konektor komunikuje się z serwerem banku wykorzystując protokół https).
Ponieważ już Ci pogratulowałem, na koniec chcę jeszcze podziękować Ci, że poświęciłeś swój czas na zapoznanie się z konektorem, tym dokumentem i dokumentacją techniczną. Jeśli masz jakieś uwagi dotyczące wymienionych zasobów lub uważasz niektóre kwestie za niejasne, nie zwlekaj i powiadom nas o tym. Będziemy Ci bardzo wdzięczni a Ty będziesz mógł korzystać z jeszcze lepszego produktu. Razem z zespołem życzymy Ci powodzenia.
John

 

Copyright XFuture 2008-2013