Przejdź do treści

Edycja kodu w Visual Studio Code w Neosie 6.1

Od wersji Neos 6.1 możliwa jest edycja kodu C# metod interfejsowych i logiki biznesowej w zewnętrznym narzędziu, jakim jest Visual Studio Code. Edycja może odbywać się równolegle w VS jak i wewnętrznym edytorze Neos Experta, ponieważ zmiany zrobione w jednym narzędziu są automatycznie aktualizowane w drugim.

UWAGA:

Neos 6.1 wprowadza domyślne wartości dla wielu kluczy w plikach *.bobj i *.bform, co powoduje, że te klucze są usuwane z plików i pliki są znacznie mniejsze. Dzieje się to nawet dla formatu 1.0.

Aby móc edytować kod w VS, muszą być spełnione pewne warunki:

  1. Musisz działać na Neosie w wersji 6.1 lub wyższej.

  2. Pliki źródłowe projektów, które chcesz edytować muszą być na lokalnym komputerze (na tym, na którym będzie działać VS), a więc całe środowisko neosa powinno działać lokalnie.

  3. Projekt neosowy musi zostać skonwertowany do wersji 6.0. W przeciwnym razie działa jedynie debugowanie, ale nie można edytować kodu.

  4. Należy zainstalować Visual Studio Code. Link: https://code.visualstudio.com/download

  5. Aby w VS Code działały zaawansowane mechanizmy wspierające edycję kodu (intellisense, skok do definicji, znalezienie listy odwołań, itp) zainstaluj .net 6.0 SDK.

    a. aby sprawdzić jaką wersję .net posiadasz z poziomu linii poleceń wpisz: dotnet \--info

    b. instalacja .net 6.0 SDK dla Windowsa 64-bit: https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-6.0.302-windows-x64-installer (ogólny link do .net 6.0: https://dotnet.microsoft.com/en-us/download/dotnet/6.0)

  6. Uruchomienie VS Code przez Neosa powoduje automatyczne doinstalowanie następujących rozszerzeń:

    a. wsparcie dla języka C#

    b. Solution Explorer (aby mieć eksplorarora solucji)

Jeśli uruchamiasz VS Code ręcznie, to jednorazowo zainstaluj te rozszerzenia (https://code.visualstudio.com/docs/editor/extension-marketplace).

Konwersja projektu na nowy format

Aby dokonać konwersji wersji projektu wejdź we właściwości projektu w Neos Expercie i w polu "Wersja projektu" wybierz 6.0, a następnie naciśnij "Zapisz".

Uważaj, gdyż ta funkcja dokonuje konwersji formatu całego projektu, a więc znacznej zmianie ulegnie wygląd plików *.bobj, *.bform, a kod C# zostanie wyodrębniony do plików *.cs. Konwersji nie należy wykonywać, jeśli na projekcie pracuje jednocześnie wiele osób na różnych branchach na gicie. Jeśli jeden branch ulegnie konwersji a inne nie, kod może przestać być mergowalny i porównywalny. Dlatego zaleca się:

  1. Wstrzymać rozwój danego projektu w określonym oknie czasowym.

  2. Domergować wszystkie branche do jednego.

  3. Dokonać konwersji na format 6.0.

  4. Na nowo odbić branche do równoległego rozwoju projektu.

Edycja kodu

Aby edytować kod w VS, pokaż okno jakiegoś obiektu w Neos Expercie a następnie kliknij w przycisk "Edytuj w Visual Studio", który znajduje się u góry okna edytora zbudowanego. Przycisk ten uruchamia VS Code w odpowiedni sposób, czyli:

a. otwierana jest właściwa solucja i odpowiedni plik źródłowy (tego obiektu, który był otwarty w Neos Experecie)

b. są automatycznie instalowane wtyczki do VS Code, jeśli ich nie ma (wtyczka wspierająca edycję w języku C#, oraz Solution Explorer)

W VS Code można już edytować kod. Aby przełączyć się na inne dokumenty można skorzystać z widoku solucji, który jest dostępny po lewej stronie (zwykle to druga ikonka od dołu).

Pisząc kod C# równolegle w VS i w Neos Experecie należy zwrócić uwagę na kilka rzeczy:

  1. w VS można dodawać w klasach elementy, które nie są metodami (np enumy, propertisy, regiony, itp) - Neos Expert nie będzie ich pokazywał na liście, ale nie zniszczy po edycji metod w Neos Expercie

  2. w VS można ustawić metody w dowolnej kolejności - Neos Expert nie widzi kolejności metod i pokazuje je alfabetycznie, ale nie zniszczy ręcznie ustalonej kolejności

  3. w VS można dodawać nowe pliki do projektów. Plików tych nie zobaczy Neos Expert, gdyż nie są to pliki powiązane z obiektami biznesowymi.

  4. zarówno w VS jaki w Neos Expercie należy unikać błędów składniowych typu nadmiar / niedomiar klamerek zamykająco-otwierających. Może to spowodować, że Neos Expert pogubi się w trakcie wczytywania metod i możemy w ogóle przestać widzieć metody w Neos Expercie.

  5. Jeśli przekonwertujemy projekt do formatu 6.0, to jest możliwa także ponowna konwersja do formatu 1.0. Należy jednak uważać, jeśli w projekcie znajduje się już jakiś kod C# poza ciałem metod. Konwersja do formatu 1.0 zapisze tylko metody, pomijając całą resztę więc projekt może się nie kompilować.

  6. Jeśli czujemy że w VS Code intellisense nie widzi wszystkiego to robimy: F1 -> Restart OmniSharp.

  7. Komendy, eventy i handlery EDA należy dodawać przez Neos Experta, dodane przez VSC bez odpowiednich atrybutów nie będą widoczne w NE oraz mogą nie działać prawidłowo.

Jak używać zewnętrznych bibliotek dll?

Projekty w formacie 6.0 mogą mieć bezpośrednie zależności do zewnętrznych bibliotek dll, bez konieczności rejestrowania ich jako moduły lub pluginy w serwerze Neos. Aby dodać zależność do biblioteki należy:

  1. Pobrać bibliotekę przez NuGeta w VS lub ręcznie z internetu i umieścić ją w folderze projektu neosowego, w następującej ścieżce: <PROJEKT>\Code\lib\.

  2. W pliku <PROJEKT>.csproj dodać wpis o referencji do biblioteki. Można go dodać poprzez otwarcie projektu w Visual Studio poprzez dodanie zależności lub ręcznie edytując ten plik. Poprawnie wpisana zależność (np. do biblioteki Google.Apis.dll) wygląda następująco:

    <Reference Include="Google.Apis, Version=1.68.0.0, Culture=neutral, PublicKeyToken=4b01fa6e34db77ab, processorArchitecture=MSIL">
      <HintPath>lib\Google.Apis.dll</HintPath>
    </Reference>
Ważne, aby ścieżka do biblioteki była względna.

  1. W odpowiednim pliku *.cs dodać using właściwej przestrzeni nazw. Można już użyć metod i klas biblioteki, a projekt powinien się poprawnie skompilować.

  2. Należy pamiętać, że do prawidłowego załadowania bibliotek przez Neosa i uruchomienia kodu, muszą one zostać skopiowane do głównego folderu serwera Neos, a następnie serwer musi zostać zrestartowany.

Koniecznie należy zwrócić uwagę, czy wszystkie inne biblioteki, których wymaga nasza biblioteka, także były i posiadały właściwe wersje. Jeśli nie jesteśmy pewni jakie są zależności między różnymi bibliotekami, można to sprawdzić na stronie nuget.org.

Pliki *.csproj po ręcznej modyfikacji są automatycznie podczytywane przez serwer Neos. Dlatego zaraz po zrobieniu czynności powyżej można pisać kod odwołujący się do zewnętrznej biblioteki, a projekt powinien się prawidłowo skompilować. Należy pamiętać, że folder lib ze wszystkimi bibliotekami należy zacommitować na gicie, gdyż biblioteki powinny być dystrybuowane razem z projektem neosowym.

Co commitować na gicie?

W formacie 1.0 projekty neosowe składały się z plików: *.bobj, *.bform, *.bproj i *.brole. W formacie 6.0 do każdego projektu dodawany jest podfolder "Code", w którym dochodzą pliki: *.cs i *.csproj, które także należy commitować na git.

Ponadto jeśli dodano zależności do zewnętrznych bibliotek, należy cały podfolder lib także zacommitować.

UWAGA:

Jedynym plikiem, który nie powinien być commitowany jest plik Autogenerated.include. Najlepiej dodać go do .gitignore.

Dziedziczenie metod a atrybut UUID w formacie 6.0

Podczas pisania metod w formacie 6.0 należy zachować spójność między dziedziczeniem Neosowym (rozpoznawanym po UUID) a dziedziczeniem w kodzie (override). Jeśli metoda oznaczona jako override ma inny UUID niż metoda bazowa, system może nie rozpoznać dziedziczenia i automatycznie zmienić override na virtual.