Własna kontrolka SSIS – część 5 – A jak sprawdzimy, czy działa?

Zanim zagłębimy się w sprawianie, żeby kontrolka robiła to, czego od niej oczekujemy warto zadać sobie pytanie – a jak sprawdzić, że to faktycznie działa? To znaczy – nie w ramach testów jednostkowych, czy poprawności kompilowania – jak się przekonać, że kontrolkę mogę podpiąć do swojego projektu SSIS i mogę z niej korzystać? Najlepiej od razu stworzyć pakiet i spróbować dodać do niego kontrolkę.

Do istniejącego Solution (jakoś ciężko mi się przyzwyczaić do tłumaczenia ‚rozwiązanie’) dodaję nowy projekt: prawy przycisk myszy w oknie Solution Explorer na nazwie, potem Add > New Project… i  Business Intelligence > Integration Services > Integration Services Project. Jeśli nie widzisz u siebie takiej opcji, to albo nie masz zainstalowanych SQL Server Data Tools, albo nie są zainstalowane poprawnie. Do nowego projektu automatycznie dodany zostaje pusty pakiet o nazwie Package1.dtsx – ale zmieniamy mu nazwę na CustomTaskTest.dtsx – bo czemu nie?

Mamy projekt, mamy pakiet. A co dalej? Spróbujmy sprawić, żeby kontrolka była widoczna w SSIS Toolbox, z którego będziemy mogli ją przeciągać do Control Flow.

DodanyProjektSSIS

Wg dokumentacji przygotowanie własnego komponentu dla SSIS to siedem prostych kroków:

  1. Stwórz nowy projekt biblioteki [ZROBIONE]
  2. Niech klasa dziedziczy po odpowiedniej klasie nadrzędnej (dla nas: Task) [ZROBIONE]
  3. Nadaj klasie odpowiedni atrybut (dla nas: DtsTaskAttribute)
  4. Przeciąż metody klasy bazowej i dopisz własny kod
  5. Opcjonalnie dodaj interfejs graficzny do konfiguracji komponentu
  6. Opcjonalnie stwórz linki i treść pomocy do komponentu
  7. Build, deploy, and debug

I gotowe! Żeby dowiedzieć się jak podłączyć stworzoną kontrolkę do SSIS Toolbox interesuje nas ten ostatni punkt. On też ma podpunkty:

  1. Podpisz bibliotekę (a dokładniej: assembly), żeby była wygenerowana z silną nazwą (strong name lub w skrócie SN)*
  2. Zbuduj assembly
  3. Skopiuj assembly do odpowiedniego katalogu Integration Services (w naszym przypadku podkatalog Task)
  4. Zainstaluj assembly w Global Assembly Cache (GAC), kontrolka automatycznie powinna zostać dodana do SSIS Toolbox
  5. A potem rozwiązuj problemy, które się pojawią

* nadal tłumaczenia na nasz język mi niespecjalnie leżą; w większości przypadków będę pisał wersje angielskie pisząc tylko raz jak to mniej więcej brzmi po polsku

Jak podpisać assembly?

Zanim podpiszemy assembly kilka słów wyjaśnienia po co to robimy i co to GAC? GAC, czyli Global Assembly Cache to w dużym uproszczeniu centralny zbiór wszystkich ogólnie dostępnych w systemie bibliotek .dll przechowywanych tak, żeby nie trzeba było troszczyć się o konflikty między nimi. Żeby tych konfliktów nie było każde assembly musi być podpisane za pomocą SN – to pomaga jednoznaczne określić bibliotekę, a przy tym podnosi bezpieczeństwo. To jednak większy temat i nie na teraz.

Na marginesie – kiedy tworzymy kawałek kodu, który chcemy podpiąć jako assembly do SQL Server w ramach CLR Integration – również należy wygenerować podpisany plik .dll. W przeciwnym przypadku baza danych, do której dołączymy assembly może wymagać ustawienia parametru TRUSTWORTHY, co nie zawsze jest dobrym pomysłem ze względu na obniżanie bezpieczeństwa.

Wracając do samego podpisywania – musimy wygenerować do tego parę kluczy (prywatny i publiczny). Możemy to zrobić na dwa sposoby: z poziomu linii komend, albo z poziomu Visual Studio. Docelowo całą operację podpisywania zrobimy w VS, ale warto też wiedzieć jak to się robi używając cmd.

Wykorzystamy do tego inny – testowy – projekt. Najpierw przechodzimy do katalogu z projektem – utworzymy wszystkie potrzebne elementy właśnie w nim. Potem trzeba namierzyć lokalizację pliku sn.exe, który wykorzystamy do podpisania assembly. Lokalizacji może być kilka – w zależności od ilości zainstalowanych wersji .NET. Ogólnie – przechodzimy do katalogu C:\Program Files (x86)\Microsoft SDKs\Windows (tutaj przypadek dla Windows 10) i wybieramy jeden z dostępnych – u mnie są to:

  • C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A
  • C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1A
  • C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A

Za wiele to nie mówi, ale biorąc pod uwagę, że Windows 10 mam z powodu bezpłatnej migracji z Windows 7 – może jest szansa że ma to związek z wersją systemu? Podejrzenie trochę blednie po zajrzeniu do podkatalogów bin w wyżej wymienionych katalogach – gdzie wygląda, że są narzędzia dla kolejnych wersji .NET(?) Czy to może mieć wpływ na wybrany „Target framework” przy konfiguracji projektu? Nic to, nie przejmujemy się dalej rozważaniami zostawiając ich roztrząsanie na moment kiedy pojawi się jakiś problem, tylko wybieramy katalog z najwyższym numerem dla SDK i NETFXTOOLS. W moim przypadku: C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools.

Samo wygenerowanie pary kluczy to jedna komenda sn.exe -k nazwa_pliku, ale wykonamy trzy kroki:

  1. Wygenerowanie pary kluczy (prywatny i publiczny) i umieszczenie ich w pliku wynikowym
  2. Wyciągnięcie z pliku wynikowego samego klucza publicznego
  3. Oczytanie tokenu klucza publicznego

Dodatkowe dwa polecenia są nam potrzebne do poznania tokenu klucza publicznego. Na razie wydaje się on zbędny, ale jeśli wykorzystamy tą samą parę kluczy do podpisania nie tylko assembly z obsługą logiki kontrolki, ale też assembly odpowiedzialne za interfejs do jej konfiguracji. Do interfejsu jeszcze mamy kawałek, ale można pomyśleć o nim już teraz i wygenerować odpowiedni token.

Wykonujemy trzy polecenia opisane wyżej:
sn.exe -k ParaKluczy.snk
sn.exe -p KluczPrywatny.out
sn.exe -t KluczPrywatny.out

PodpiszAssemblyCmd

Na obrazku nazwy plików się różnią od przykładu, ale idea jest raczej zrozumiała.

Mając klucze możemy wracać do podpisania assembly. Prawym przyciskiem myszy klikamy na nazwę projektu ssis-winscptask (albo mając zaznaczony projekt z menu wybieramy PROJECT > ssis-winscptask Properties…) i w oknie właściwości przechodzimy do zakładki Signing.

AssemblySigning

Po zaznaczeniu Sign the assembly możemy albo utworzyć nową parę kluczy wybierając <New…> albo za pomocą <Browse…> wybrać plik .snk z wygenerowanymi wcześniej kluczami. Tym razem tworzymy klucz z poziomu VS, to wybieramy <New…>. W nowym oknie podajemy nazwę pliku, do którego mają zostać zapisane klucze i zostawiamy wybraną opcję sha25RSA. Możemy też podać hasło, żeby lepiej je chronić, ale damy sobie z tym spokój. Po naciśnięciu OK wszystko gotowe, a w projekcie pojawia się plik z parą kluczy.

AssemblySNKFile

Zwracamy przy okazji uwagę, że nie znamy tokenu klucza publicznego dla tak wygenerowanego pliku .snk, ale do tego wrócimy później.

Zarejestruj assembly w GAC

Mamy wygenerowane klucze, to kompilujemy kod do biblioteki – np. przez kliknięcie prawym przyciskiem myszy na nazwie projektu ssis-winscptask i wybranie Build albo Rebuild. W podkatalogu bin projektu powstanie plik ssis-winscptask.dll – nasza wynikowa assembly. Rejestrowanie w GAC to wykorzystanie innego narzędzia z tego samego katalogu co sn.exe. Tym razem używamy gacutil.exe z opcją if (i = install, f = forced):

C:\Users\brata_000\Source\Repos\ssis-winscptask\ssis-winscptask\ssis-winscptask\bin\Debug>"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\gacutil.exe" /if ssis-winscptask.dll

Ale uwaga – bez uprawnień admina ani rusz:

Microsoft (R) .NET Global Assembly Cache Utility. Version 4.0.30319.0
Copyright (c) Microsoft Corporation. All rights reserved.

Failure adding assembly to the cache: Administrator permissions are needed to use the selected options. Use an administrator command prompt to complete these tasks.

Uruchamiamy konsolę cmd jako Administrator i ponawiamy polecenie. Tym razem jednak zrezygnujemy z całego nagłówka mówiącego o użytym narzędziu wykorzystując opcję /nologo:

C:\Users\brata_000\Source\Repos\ssis-winscptask\ssis-winscptask\ssis-winscptask\bin\Debug>"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\gacutil.exe" /if ssis-winscptask.dll /nologo

Komunikat jest już taki, jakiego oczekiwaliśmy: Assembly successfully added to the cache. Sprawdzamy jeszcze, czy wszystko OK wykorzystując opcję l z nazwą assembly:

C:\Users\brata_000\Source\Repos\ssis-winscptask\ssis-winscptask\ssis-winscptask\bin\Debug>"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\gacutil.exe" /l ssis-winscptask /nologo
The Global Assembly Cache contains the following assemblies:
ssis-winscptask, Version=1.0.0.0, Culture=neutral, PublicKeyToken=62afeffbe3b324e5, processorArchitecture=MSIL

Number of items = 1

Czyli jest dobrze. Dodatkowo dowiedzieliśmy się jaki jest token klucza publicznego. Dla porządku sprawdzamy jeszcze wyrejestrowanie assembly z GAC za pomocą opcji u:

C:\Users\brata_000\Source\Repos\ssis-winscptask\ssis-winscptask\ssis-winscptask\bin\Debug>"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\gacutil.exe" /u ssis-winscptask /nologo

Assembly: ssis-winscptask, Version=1.0.0.0, Culture=neutral, PublicKeyToken=62afeffbe3b324e5, processorArchitecture=MSIL
Uninstalled: ssis-winscptask, Version=1.0.0.0, Culture=neutral, PublicKeyToken=62afeffbe3b324e5, processorArchitecture=MSIL
Number of assemblies uninstalled = 1
Number of failures = 0

C:\Users\brata_000\Source\Repos\ssis-winscptask\ssis-winscptask\ssis-winscptask\bin\Debug>"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\gacutil.exe" /l ssis-winscptask /nologo
The Global Assembly Cache contains the following assemblies:

Number of items = 0

Usprawniamy wdrażanie

Gra i buczy, ale takie uruchamianie instalacji nowej wersji assembly w GAC za każdym razem w otwartej z boku konsoli jest mało fajne. A jeszcze nie dodaliśmy kroku z kopiowaniem biblioteki do odpowiedniego katalogu Integration Services, żeby widzieć kontrolkę w SSIS Toolbox. Można napisać batch, który wykona wszystkie te operacje, ale można też dać więcej pracy Visual Studio i wykorzystać Build Events.

ProjectBuildEvents

Interesuje nas okno Post-build event command line, do którego wstawiamy serię poleceń do wykonania po każdym zakończonym z sukcesem (re)buildzie (zostawiamy On succesful build na liście Run the post-build event). Ten sposób ma swoją dużą zaletę – możemy skorzystać z kilku predefiniowanych makr, które możemy wykorzystać w kodzie. Żeby zobaczyć te makra wystarczy kliknąć guzik Edit post-build … i w nowym oknie nacisnąć Macros >>. Do makr odwołujemy się przez składnię z nawiasami i znakiem dolara, np.: $(OutDir).

Do skryptu wykorzystamy wzór z książki „Extending SSIS with .NET Scripting: A Toolkit for SQL Server Integration Services”. W rozdziale 16. „Create a custom task” jest fragment kodu, który dopasujemy do naszych potrzeb ustawiając odpowiednie ścieżki i komunikaty po polsku:

cd $(ProjectDir)
@SET TASKDIR="C:\Program Files (x86)\Microsoft SQL Server\130\DTS\Tasks\"
@SET GACUTIL="C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\gacutil.exe"
Echo Instalacja $(OutDir)$(TargetFileName) w GAC
%GACUTIL% /if "$(OutDir)$(TargetFileName)" /nologo
Echo Kopiowanie "$(OutDir)$(TargetFileName)" do katalogu Tasks
copy "$(OutDir)$(TargetFileName)" %TASKDIR%

Uwaga – ponieważ znowu wywołujemy gacutil.exe, które wymaga uprawnień administratora – Visual Studio musimy uruchamiać jako administrator. Po uruchomieniu proces powinien działać i rejestrować w GAC oraz kopiować assembly do katalogu Task.

Nasza kontrolka wciąż jednak nie będzie widoczna w SSIS Toolbox. Pora na dodanie do kodu DtsTaskAttribute:

[DtsTask(
Description = "WinSCP Task - obsługa SFTP, FTP/TLS, SCP za pomocą biblioteki WinSCP",
DisplayName = "WinSCP Task"
)]

DtsTaskAttribute

Wybraliśmy dwa pierwsze parametry z opisem i wyświetlaną nazwą. Teraz po skompilowaniu projektu i uruchomieniu Visual Studio ponownie kontrolka powinna być widoczna w SSIS Toolbox. Jeśli nie jest – naciśnij prawym przyciskiem myszy w dowolnym miejscu SSIS Toolbox i wybierz Refresh Toolbox.

CustomTask_SSISToolbox

Tyle to trzeba było mozołu dla sporządzenia jednego stołu. Kontrolka jest, można ją dodać do Control Flow, ale po dwukrotnym kliknięciu w nią pojawia się komunikat o braku jej edytora. O tym jednak już w kolejnych etapach prac.

Reklamy

Jedna uwaga do wpisu “Własna kontrolka SSIS – część 5 – A jak sprawdzimy, czy działa?

  1. Pingback: Własna kontrolka SSIS, część 6 – podłączamy się do serwera SFTP | Takie tam

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Wyloguj / Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Wyloguj / Zmień )

Zdjęcie na Facebooku

Komentujesz korzystając z konta Facebook. Wyloguj / Zmień )

Zdjęcie na Google+

Komentujesz korzystając z konta Google+. Wyloguj / Zmień )

Connecting to %s