- 1. Założenia projektu
- 2. Krótki wstęp teoretyczny
- 3. Zakres funkcjonalności
- 4. Opis implementacji
- 5. Przykładowe dane
- 6. Prezentacja testów jednostkowych
- 7. Podsumowanie
- 8. Literatura
- 9. Kod źródłowy
Celem CMAPI (Company Management API) jest umożliwienie obsługi struktury firmy będącej strukturą hierarchiczną. Elementami w hierarchii będą pracownicy wraz z ich danymi personalnymi. Głównym założeniem projektu jest wykorzystanie typu HierarchyID do przechowywania wspomnianych danych hierarchicznych.
- C#
- Microsoft SQL Server
- Typ HierarchyID
- Visual Studio Testing Tools
CMAPI jest biblioteką udostępniającą zestaw dwóch klas głównych (Employee i Company), z których jedna jest placeholderem do przechowywania danych o pracowniku, a druga daje dostęp do grupy metod działających na tych danych.
Do stworzenia API wykorzystałem typ HierarchyID - używamy go, aby przedstawić pozycję w hierarchii. Kolumna typu hierarchyid nie reprezentuje automatycznie drzewa. Do aplikacji należy generowanie i przypisywanie wartości hierarchyid w taki sposób, aby pożądana relacja między wierszami była odzwierciedlona w wartościach.
Poprzez zestaw metod API pozwala użytkownikowi na dodawanie/usuwanie pracowników oraz tworzenie wybranych raportów.
Oprócz samego API, w projekcie uwzględniłem również testy jednostkowe, skrypty służące do utworzenia przykładowej bazy oraz aplikację konsolowa, służącą do przedstawienia przykładu działania stworzonego API.
Przechowuje dane na temat pracowników
Udostępniają manipulację danymi pracowników
Parametry
- id <<int>>
- level <<string>>
- firstName <<string>>
- lastName <<string>>
- position <<string>>
- salary <<int>>
Typ zwracany
- <<void>>
Parametry
- id <<int>>
Typ zwracany
- <<void>>
Parametry
- firstName <<string>>
Typ zwracany
- <<void>>
Parametry
- lastName <<string>>
Typ zwracany
- <<void>>
Parametry
- level <<string>>
Typ zwracany
- <<void>>
Parametry
- <<void>>
Typ zwracany
- <<void>>
Parametry
- id <<int>>
Typ zwracany
- <<Employee>>
Parametry
- level <<string>>
Typ zwracany
- <<Employee>>
Parametry
- firstName <<string>>
Typ zwracany
- <<Employee>>
Parametry
- lastName <<string>>
Typ zwracany
- <<Employee>>
Zwróć pracownika ze specyficznym HierarchyID wraz z jego podwładnymi - GetEmployeeWithSubordinates()
Parametry
- level <<string>>
Typ zwracany
- <<List<Employee>>>
Parametry
- <<void>>
Typ zwracany
- <<List<Employee>>>
Parametry
- <<void>>
Typ zwracany
- salary <<int>>
Parametry
- <<void>>
Typ zwracany
- salary <<int>>
CMAPI udostępnia procedury wykonujące operacje na rekordach tabeli pracowników (Employee) w bazie danych. Do zaimplementowania wykorzystałem klasy w języku C#, które wykonują zapytania SQL do bazy danych, które uruchamiają żądane procedury. W procedurach wykonywane są instrukcje SQL, które korzystają m. in. z typu hierarchyid.
Wszystkie funkcje są dostępne z poziomu interaktywnej konsolowej aplikacji (demo), przyjmującej input od użytkownika, który decyduje co chce zrobić. Jest to przykład implementacji API w działającej aplikacji - funkcje można wdrożyć również do istniejącego wcześniej systemu.
W ramach aplikacji demonstrującej działanie CMAPI, możemy do bazy dodać gotowe przykładowe dane - są to testowe dane firmy, która korzysta z hierarchicznej struktury danych. Zbieżność imion i nazwisk jest przypadkowa.
Do testowania CMAPI wykorzystałem narzędzia do testowania udostępnione przez Visual Studio. W projekcie testowym, na przykładowych danych przetestowane zostały wszystkie metody wykorzystane w API, poniżej przedstawiam wyniki przeprowadzonych testów.
Typ hierarchyid zdaje się być bardzo dobrą opcją do przetwarzania danych hierarchicznych - jest szybki i łatwy w użyciu. Oprócz tego, udostępnia również wiele pomocnicznych funkcji (takich jak IsDescendantOf), które są bardzo przydatne, a musiałyby być dodatkowo zaimplementowane w przypadku własnoręcznego rozwiązania problemów tego typu.
Z drugiej strony, wsparcie C# dla hierarchyid nie jest pełne - przykładem może być konieczność ciągłego parsowania typu danych z SqlHierarchyId do string, by mogły one zostać przetworzone przez bazę danych. Słyszałem również że wydajność hierarchyid w bazach większego kalibru potrafi być nieakceptowalna - jednak w przypadku małych baz, może nadać się idealnie.
Do stworzenia projektu wykorzystałem głównie oficjalną dokumentację Microsoftu, oraz pomniejsze strony służące jako poradniki do obsługi typu hierarchyid:
- https://codingsight.com/how-to-use-sql-server-hierarchyid-through-easy-examples/
- https://docs.microsoft.com/en-us/sql/t-sql/data-types/hierarchyid-data-type-method-reference?view=sql-server-ver15
- https://docs.microsoft.com/en-us/dotnet/csharp/
- https://docs.microsoft.com/en-us/sql/relational-databases/tables/tutorial-using-the-hierarchyid-data-type?view=sql-server-ver15
- https://www.sqlshack.com/use-hierarchyid-sql-server/
Kod źródłowy wszystkich skryptów T-SQL wykorzystanych w projekcie znajduje się w folderze o nazwie “dbsetup”. Znajdują się tam skrypty dotyczące tworzenia bazy, tabeli Employee, dodawania i usuwania potrzebnych procedur oraz pomniejszych skryptów służących do testowania aktualnego stanu bazy danych.