Pluginy¶

W technologii neos, od wersji 4.0.8 istnieje możliwość pisania i używania własnych pluginów - czyli bibliotek dll napisanych w Visual Studio. Pluginy są po to, aby używać własnego kodu C# w aplikacjach bez rozszerzania samego kodu serwera Neos. Serwer Neos powinien być używany w postaci dostarczonej przez ZRT i nie mieć żadnych modyfikacji indywidualnych ani rozszerzeń.

Poniżej opisano, jak w prosty sposób napisać i użyć własny plugin.

Zalecamy wykorzystanie Visual Studio 2015 Express i targetować projekty na .net 4.6. https://visualstudio.microsoft.com/pl/vs/older-downloads/ (Mimo, że na górze jest info o śćiąganiu 2019 Community, to szukać poniżej jest wersja 2015 Express). Źródła C# najlepiej commitować na git na repozytorium założonym dla klienta, dla którego rozwijamy plugina.

Zakładamy w Visual Studio nowy projekt we własnej solucji. W nazwie projektu oraz w jego przestrzeni nazw zaleca się użyć słowa "plugin" aby uniknąć konfliktów nazw w innymi bibliotekami i projektami neosowymi. Projekt może nie mieć żadnej referencji ani żadnego związku z kodem neosa. Jeśli jednak chcemy rozwijać drivery EDE, możemy na liście referencji umieścić Neos.Common.dll. Jeśli chcemy korzystać z warstwy dostępu do bazy danych, możemy na liście referencji umieścić Neos.Core.dll. Kod przykładowego projektu o nazwie DemoPlugin z jedną klasą umieszczono poniżej.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Neos.DemoPlugin
{
  /// <summary>
  /// Klasa demo w pluginie
  /// </summary>
  public class DemoClass
  {
    /// <summary>
    /// Pole testowe
    /// </summary>
    public string TestField;
  }
}

Po kompilacji tego projektu otrzymujemy nową bibliotekę DemoPlugin.dll. Warto we właściwościach projektu włączyć generowanie pliku xml z dokumentacją biblioteki. Dzięki temu dokumentacja będzie podpowiadać się w edytorze C# jako intellisense.

Aby serwer neosa widział tą bibliotekę należy ją zarejestrować w pliku smd jako plugin. Poniżej przykład sekcji [Plugins] z wskazanymi bibliotekami Neos.Common.dll, Neos.BusinessPlatform.dll oraz DemoPlugin.dll.

[Plugins]
Items=common;demo;bp    <=== bp koniecznie musi być jako ostatnie
common:Name=Neos.Common
common:Version=1.0.0.0
common:Culture=neutral
common:PublicKeyToken=null
bp:Name=Neos.BusinessPlatform
bp:Version=1.0.0.0
bp:Culture=neutral
bp:PublicKeyToken=null
demo:Name=DemoPlugin
demo:Version=1.0.0.0    <=== wersja musi być zgodna z AssemblyVersion skompilowanego pluginu
demo:CodeBase=.\demo    <=== wskazanie lokalizacji plików pluginu
demo:Culture=neutral
demo:PublicKeyToken=null
demo:Namespaces=Neos.DemoPlugin

Warto zauważyć, że dla pluginu demo pojawił się wpis demo:Namespaces=Neos.DemoPlugin. Wpis ten zawiera przestrzenie nazw (oddzielane średnikiem lub przecinkiem), które automatycznie zostaną użyte w kodzie C# jako using. Klasy tych przestrzeni będą też dostępne w intellisense edytora C#.

Oczywiście musimy zapewnić aby pliki DemoPlugin.dll oraz DemoPlugin.xml znalazły się w katalogu serwera neos.

Poniżej znajduje się przykład wykorzystania plugina DemoPlugin.dll w przykładowej metodzie dowolnego obiektu biznesowego dowolnego projektu.

public static void TestPlugina()
{
#if DEMOPLUGIN
  DemoClass x = new DemoClass();
  x.TestField = "akuku";
  API.ShowBalloonHint("Jest plugin demo","Uwaga",IconType.INFORMATION);
#else  
  API.ShowMessageBox("Nie ma plugina demo","Uwaga");
#endif  
}

Klasa DemoClass jest dostępna od razu bez konieczności ręcznego wpisywania using-ów, ani podawania pełnej nazwy klasy wraz z przestrzenią nazw. Warto zauważyć, że klasa i jej zawartość jest też podpowiadana w intellisense.

Dodatkowo dla każdego załadowanego plugina definiowana jest dyrektywa zgodna z jego nazwą, przy czym kropki są zamieniane na znaki podkreślenia a wszystkie znaki są podnoszone do wielkich liter. Tak więc plugin DemoPlugin.dll jest określany dyrektywą DEMOPLUGIN.

Użycie #if DEMOPLUGIN nie jest obowiązkowe, ale pozwala napisać bardziej bezpieczny kod - taki, który skompiluje się poprawnie zarówno w przypadku istnienia biblioteki plugina w serwerze, jak i w przypadku jej braku.

Repozytoria na gicie¶

DBR zaleca aby wszystkie repozytoria z pluginami do neosa znajdowały się w przestrzeni nazw neos-plugins. Wyjątkiem są pluginy wchodzące w skład obszarów, oraz niezbędne do działania nowego systemu Teneum, gdzie przechowywane są w repozytorium S4, w podkatalogu danego obszaru.

Pobieranie zależności¶

Paczki z np. Neos.Core.dll znajdują się na naszym repozytorium NuGet. W razie problemów ze wciąganiem zależności i ich brakiem proszę sprawdzić konfigurację NuGeta Instrukcja NuGet.