search

soneta / Soneta.MsBuild.SDK

Sdk stworzone przez firmę Soneta pozwalające automatycznie skonfigurować oraz uzupełnić projekty dodatków o niezbędne elementy potrzebne do współpracy z oprogramowaniem enova.
MIT License
8 stars 12 forks source link

readme

Wersja SDK 1.1.4 jest wymagana od wersji enova265 2306.0.0-net (NET 6)

Wersja SDK 1.1.2 jest kompatybilna z poprzednimi wersjami bibliotek FrameworkSoneta, a także do wykorzystania do kompilacji w netstandard2.0 od wersji enova365 2204.3.6

Wersja SDK 1.1.0 jest do wykorzystania od wersji enova365 2106.0.0

!!! Korzystanie z tej wersji SDK wymaga usunięcia z plików modul.business.xml i modul.config.xml wpisu (jeżeli występuje):

<import>generator<import>

Pozostawienie wpisu spowoduje konflikt dwóch sposobów pobierania generatora - nowego, automatycznego z SDK oraz starego - kopiowania generatora do folderu projektu, co zaskutkuje wygenerowaniem pustych plików.cs przez generator.

Soneta.MsBuild.SDK

NuGet NuGet Build Status

Wstęp

SDK (Software Development Kit) jest to zestaw narzędzi dla programistów niezbędnych w tworzeniu aplikacji z danej biblioteki. Soneta.MsBuild.SDK jest zestawem narzędzi niezbędnym do tworzenie dodatków dla sytemu enova365. Pozwala automatycznie skonfigurować projekt oraz uzupełniać projekty dodatku o niezbędne elementy potrzebne do wsprółpracy z oprogramowaniem enova365. Do elementów konfiguracyjnych Soneta SDK zaliczamy następujące pliki wraz z ich przeznaczeniem:

Pierwsze kroki

Zdefiniowanie wersji Soneta.sdk.

W celu zaimportowania Soneta.MsBuild.SDK do projektu dodatku w pliku "nazwaprojektu.csproj" edytujemy linię dotyczącą projektu: 

   <Project Sdk="Soneta.Sdk/numerWersji">

Po zapisie zmian zostanie wykonana automatyczna konfiguracja projektu.

W przypadku gdy w solucji znajduje się wiele projektów, by uniknąć konieczności zmian w każdym projekcie numeru wersji, istnieje możliwość stworzenia pliku nadrzędnego "global.json" (poza projektami) o zawartości: 

   { 
     "msbuild-sdks": { 
        "Soneta.Sdk": "numerWersji" 
      }
   }

Dzięki czemu w plikach ".csproj" wymagany będzie tylko wpis bez konieczności umieszczania numeru wersji. Najnowszą opublikowaną wersję dodatku Soneta.MsBuild.SDK znajdziemy tutaj

Zdefiniowanie wersji bibliotek

Powinniśmy także utworzyć plik "Directory.Build.props" o zawartości:

 <?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <SonetaPackageVersion>1905.0.1</SonetaPackageVersion>
    <SonetaTargetFramework>net46</SonetaTargetFramework>
  </PropertyGroup>
</Project>

Plik „Directory.Build.props” zawiera informację o wersji bibliotek pobieranych przez Soneta.SDK. Dzięki temu nie musimy już manualnie dodawać referencji do bibliotek Sonety tylko globalnie definiujemy wersję bibliotek z której ma korzystać dodatek. Należy tutaj wspomnieć, że dzięki takiemu rozwiązaniu możemy łatwo zmienić wersję bibliotek, którą chcemy wykorzystać w naszym dodatku. Wersję bibliotek Sonety definiujemy za pomocą parametru "SonetaPackageVersion", który wskazuje na wersję paczki Soneta.Product.Modules . W pliku „Directory.Build.props” mamy także możliwość zdefiniowania własnych zmiennych, które mogą być później używane w naszych projektach.
Kolejnym ważnym elementem znajdującym się w pliku „Directory.Build.props jest wersja .NET, którą używamy w naszej solucji. Dzięki temu każdy plik ".csproj" może odwołać się do parametru SonetaTargetFramework zdefiniowanego w jednym miejscu. Poniżej przedstawiono zawartość pliku "*.csproj" wykorzystujący Soneta.MsBuild.SDK.

<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Soneta.Sdk">
  <PropertyGroup>
    <TargetFramework>$(SonetaTargetFramework)</TargetFramework>
  </PropertyGroup>
</Project>

Informacje Ogólne

Soneta.sdk obsługuje 3 typy projektów, które można stworzyć. W zależności od rodzaju projektu pobierane są inne biblioteki. Możemy stworzyć takie projekty jak:

Istnieje możliwość stworzenia projektu testowego, który nie podąża za wyżej opisaną konwencją. Można to zrobić poprzez ustawienie w pliku .csproj flagi \true\.
Możemy także wykorzystać takie parametry jak:

Wraz z bibliotekami jest pobierana odpowiednia wersja generatora. Zadaniem generatora jest przekonwertowanie plików „.xml” na pliki „.cs”. Konwersja wykonywana jest podczas budowania dodatku.

Studium przypadku

Korzystanie z bibliotek Soneta, niedostarczanych automatycznie przez Soneta.MsBuild.SDK (na przykładzie dodatków opartych o biblioteki WinForms)

W wielu przypadkach do utworzenia lub zaktualizowania dodatku w oparciu o Soneta Sdk, wszystkie niezbędne biblioteki Soneta zostaną dostarczone automatycznie. Czasem jednak istnieje potrzeba skorzystania z bibliotek nie ujętych w zakresie SonetaPackage. Przykładem może być aktualizacja dodatku, którego interfejs użytkownika został zbudowany przed wprowadzeniem mechanizmu form.xml, za pomocą bibliotek opartych o technologię WinForms. W większości przypadków najlepszym rozwiązaniem takiego problemu jest zaktualizowanie dodatku do formatu form.xml, który jest w pełni wspierany i kompatybilny z Sdk.

Z przyczyn biznesowych lub technicznych takie rozwiązanie nie zawsze jest możliwe. Aby mimo wszystko umożliwić takim dodatkom korzystanie z Soneta.MsBuild.SDK można jawnie zareferować do brakujących bibliotek, np. znajdujących się w folderze instalacyjnym programu enova365. Z poziomu Visual Studio referencję można dodać bezpośrednio z interfejsu użytkownika. W tym celu w oknie eksploratora solucji należy kliknąć odpowiedni projekt dodatku prawym przyciskiem myszy. Następnie, w menu kontekstowym, wybrać Add/Reference i wskazać odpowiedni plik DLL. Referencję można także dodać bezpośrednio w pliku projektu *.csproj, dopisując do niego poniższy fragment kodu. 

<ItemGroup>
  <Reference Include="Soneta.Forms">
    <HintPath>C:\Program Files (x86)\Soneta\enova365 1908.0.1.17324\Soneta.Forms.dll</HintPath>
    <SpecificVersion>false</SpecificVersion>
    <Private>false</Private>
  </Reference>
</ItemGroup>

Jeśli istnieje potrzeba referowania do większej ilości bibliotek, można podać lokalizację, pod którą będą one wyszukiwane. W takim wypadku nie ma potrzeby dłużej korzystać z elementu HintPath. W tym celu w pliku projektu należy dodać poniższy fragment, gdzie w elemencie ReferencePath należy umieścić ścieżkę do folderu zawierającego biblioteki, do których odnosi się referencja.

<PropertyGroup>
  <ReferencePath>C:\Program Files (x86)\Soneta\enova365 1908.0.1.17324\</ReferencePath>
  <AssemblySearchPaths>$(AssemblySearchPaths);$(ReferencePath);</AssemblySearchPaths>
</PropertyGroup>

Warto zwrócić uwagę, że jeśli zareferowane biblioteki, same w sobie referują do bibliotek Soneta dostarczanych przez Sdk, wersja bibliotek z obu źródeł powinna być zgodna. W przypadku podniesienia wersji SonetaPackageVersion w pliku Directory.Build.props pomimo różnicy wersji bibliotek DLL, nadal mogą one zachować zgodność. Może się jednak okazać, że w nowej paczce SonetaPackage zaszły znaczące zmiany uniemożliwiające dalsze współdziałanie bibliotek. W takim wypadku konieczne będzie zaktualizowanie referencji w dodatku do nowszej wersji bibliotek Soneta.

Współpraca

W celu zaproponowania zmian należy stworzyć Pull Request do gałęzi develop. Po podjęciu decyzji o wydaniu nowej wersji branch develop zostanie zmergowany do mastera i dodatek zostanie automatycznie wydany.

  1. Po poprawnym zbudowaniu Sdk ustawiamy się w konsoli na ścieżce \bin\Release
  2. Wykonujemy push do naszego lokalnego folderu z paczkami: 
    dotnet nuget push nazwaPaczki.nupkg -s C:\Users....nuget\packages
  3. Dzięki powyższym czynnościom nasze SDK będzie widoczne dla naszych nowo utworzonych projektów.

Proces wydawania nowych wersji

Dokument instrukcja wydania szczegółowo opisuje potrzebne czynności zmierzające do wydania nowej wersji.