diff --git a/Diplomarbeitsbuch-individueller-teil-Konstantin-Hintermayer.md b/Diplomarbeitsbuch-individueller-teil-Konstantin-Hintermayer.md index 2a16f73..48685e8 100644 --- a/Diplomarbeitsbuch-individueller-teil-Konstantin-Hintermayer.md +++ b/Diplomarbeitsbuch-individueller-teil-Konstantin-Hintermayer.md @@ -17,7 +17,7 @@ Meine Zuständigkeiten und Verantwortlichkeiten: ### Motivation -Lernen von ASP.NET und der Entwicklung mit Blazor und Oqtane. Ich habe Interesse an dem Thema Webentwicklung. Privat entwickel ich schon seit Jahren viel mit React.JS. +Meine Motivation war das Lernen von ASP.NET und der Entwicklung mit Blazor und Oqtane. Ich habe Interesse an dem Thema Webentwicklung. Privat entwickle ich schon seit Jahren viel mit React.JS. ## 2. Anforderungen an das entwickelte Modul bzw. die Funktionalität @@ -27,25 +27,24 @@ Lernen von ASP.NET und der Entwicklung mit Blazor und Oqtane. Ich habe Interesse ## 3. Technische Grundlagen Mein Aufgabenbereich umfasst einerseits die Entwicklung eigener Module, sowie das Bereitstellen des Services. Als Betriebssystem habe ich mich für Linux entschieden, einfach, da ich mit Linux im Serverumfeld die meisten und besten Erfahrungen gemacht habe. -(Diese Entscheidung wurde gemeinsam getroffen:) -Auch steht die Wahl der Programmiersprache und des CMS an. Nachdem wir im Unterricht fast ausschließlich mit C# entwickelt haben und nicht in eine komplett unbekannte Entwicklungsumgebung abdriften wollten, haben wir uns für Webentwicklung mit ASP.NET Core 9 und (Upgrade im Lauf der Diplomarbeit auf .NET Core 10) dem CMS Oqtane entschieden. Auch hier gab es einige Kandidaten: +Auch steht die Wahl der Programmiersprache und des CMS an. Nachdem wir im Unterricht fast ausschließlich mit C# entwickelt haben und nicht in eine komplett unbekannte Entwicklungsumgebung abdriften wollten, haben wir uns für die Webentwicklung mit ASP.NET Core 9 (Upgrade im Lauf der Diplomarbeit auf .NET Core 10) und dem CMS Oqtane entschieden. Auch hier gab es einige Kandidaten: - Piranha CMS - >Piranha erscheint auf den ersten Blick nicht so flexibel wie Oqtane, basiert auf .NET 8.0 und wird nicht so aktiv gewartet. + >Piranha erscheint auf den ersten Blick nicht so flexibel wie Oqtane, es basiert auf .NET 8.0 und wird nicht so aktiv gewartet. - Umbraco - >Viel Arbeit mit Partials, welche in der Admin Oberfläche geschieht, aber sehr gut dokumentiert. Im großen und ganzen wirkt Umbraco nicht so flexibel. + >Viel Arbeit mit Partials, welche in der Admin Oberfläche geschieht, aber sehr gut dokumentiert. Im Großen und Ganzen wirkt Umbraco nicht so flexibel. - DNN / Dot Net Nuke >Platzhirsch. Kennt man, wird von der DNN Foundation gewartet. Arbeitet mit dem Dotnet Framework, welches nicht unter Linux läuft. Und ein Windows Server würde ich ich nicht einfach so ins Internet, abgesehen von den Lizenzkosten, die das kosten würde. - Oqtane - >Schlecht dokumentiert, auf den ersten Blick sehr modular und flexibel. + >Oqtane wirkt auf den ersten Blick sehr modular und flexibel, die schlechte Dokumentation ist erst im Nachhinein aufgefallen. -Am Ende haben wir uns für das Oqtane Framework trotz seiner schlechten Dokumentation entschieden. +Aufgrund seiner sehr hohen Flexibilität, haben wir uns am Ende für Oqtane entschieden. -Im Bereich der Datenbanken musste ich mir ein paar Fragen stellen. +Im Bereich der Datenbanken musste ich mir ein paar Fragen stellen: 1. Auf welche Art Datenbank setzen wir? SQL, NoSQL, Graph, ... -2. Mit welcher speziellen implementiereung bekommen wir Support und haben Wissen im Team? -3. Ist das auserkorene System kompatibel mit dem CMS auf dem wir aufbauen? +2. Mit welcher speziellen Implementierung bekommen wir Support und bei welcher haben wir Vorwissen im Team? +3. Ist das auserkorene System kompatibel mit dem CMS, auf dem wir aufbauen? -Es war von Anfang an klar, dass es ein SQL basiertes System wird, da wir im Team nur mit SQL-basierten Systemen erfahrungen haben. Außerdem unterstützt unser CMS (Oqtane) nur SQL basierte Systeme. In der Linuxwelt kommen jetzt nur noch ein paar Datenbanken in die Auswahl: PostgreSQL, MySQL / MariaDB, SQLite. Da ist die Wahl auf PostgreSQL gefallen. Grund dafür war meine Vorerfahrung mit diesem DBMS, welche ich im Nebenjob errungen habe. +Es war von Anfang an klar, dass es ein SQL-basiertes System wird, da wir im Team nur mit SQL-basierten Systemen Erfahrungen haben. Außerdem unterstützt unser CMS (Oqtane) nur SQL-basierte Systeme. In der Linuxwelt kommen jetzt nur noch ein paar Datenbankmanagementsysteme in die Auswahl: PostgreSQL, MySQL / MariaDB, SQLite. Da ist die Wahl auf PostgreSQL gefallen. Grund dafür war meine Vorerfahrung mit diesem Datenbankmanagementsystem, welche ich in meinem Nebenjob errungen habe. # Technologie @@ -54,27 +53,27 @@ Oqtane ist ein Framework und CMS zur Entwicklung von Webseiten mithilfe von ASP. In dieser Diplomarbeit fokussieren wir uns hauptsächlich auf `Themes` und `Modules`, aber es gibt auch `Language Packs` und `Pure Extensions`. [^6] -Ein `Module` (Modul) soll neue Funktionalitäten in das CMS hinzufügen und ein `Theme` soll die ganze Gestaltung der Website (die Shell) festlegen. [^6] +Ein `Module` (Modul) soll neue Funktionalitäten in das CMS hinzufügen und ein `Theme` soll die ganze Gestaltung der Webseite (die Shell) festlegen. [^6] [^5]: https://www.oqtane.org/#about [^6]: https://docs.oqtane.org/dev/extensions/index.html ### Architektur eines Moduls -Ein Modul in Oqtane besteht aus 4 Projekten. Server, Client, Shared und Package. +Ein Modul in Oqtane besteht aus vier Projekten: -Im Server-Projekt liegt Sourcecode, welcher serverseitig ausgeführt werden soll. In der Praxis bedeutet das: alle Repositories, Controller, Manager, Migrationen und Server-Services (entwickelt nach einem Interface definiert im Client) und Server-Startuplogik. +- Im Server-Projekt liegt Sourcecode, welcher serverseitig ausgeführt werden soll. Dazu gehören unter anderem alle Repositories, Controller, Manager, Migrationen und Server-Services und Server-Startuplogik. -Im Client-Projekt liegen Code und Razor-Komponenten für den Client. Also Client-Staruplogik, Client-Services (+ Inferfaces dafür, die Services hier sollen lediglich die Server-Services über HTTP aufrufen), Ressourcendateien (.resx), die Komponenten / das User Interface und die Moduldefinitionen für jedes Modul. +- Im Client-Projekt liegen Code und Razor-Komponenten für den Client. Also Client-Startuplogik, Client-Services, Ressourcendateien (.resx), die Komponenten / das User Interface und die Moduldefinitionen für jedes Modul. -Im Shared-Projekt wird geteilter Sourcecode abgelegt, der server- und clientseitig verwendet wird. In der Praxis bleibt es hierbei bei den EntityFramework-Modellen zum Speichern der Daten im Arbeitsspeicher. +- Im Shared-Projekt wird geteilter Sourcecode abgelegt, der server- und clientseitig verwendet wird. In der Praxis bleibt es hierbei bei den EntityFramework-Modellen zum Speichern der Daten im Arbeitsspeicher. -Im Package Projekt findet man Skripte zum Debuggen und Releasen eines Moduls. Und die NuGet-Spezifikation. -- Beim Debug werden die DLLs, PDBs und statischen Assets wie Skripte und Stylesheets der 3 anderen Projekte in den bereits gebauten Oqtane.Server `oqtane.framework/oqtane.server/bin/debug/net10.0/...` kopiert. -- Beim Release wird ein NuGet-Paket erstellt und unter oqtane.framework/oqtane.server/Packages abgelegt. Dort abgelegte NuGet-Pakete werden beim nächsten Start des Oqtane Servers installiert (DB Migrationen werden gemacht und die Pakete entpackt). +- Im Package Projekt findet man Skripte zum Debuggen und Releasen eines Moduls und die NuGet-Spezifikation. + - Beim Debug werden die DLLs, PDBs und statischen Assets wie Skripte und Stylesheets der drei anderen Projekte in den bereits gebauten Oqtane.Server `oqtane.framework/oqtane.server/bin/debug/net10.0/...` kopiert. + - Beim Release wird ein NuGet-Paket erstellt und unter oqtane.framework/oqtane.server/Packages abgelegt. Dort abgelegte NuGet-Pakete werden beim nächsten Start des Oqtane Servers installiert (Datenbank Migrationen werden gemacht und die Pakete entpackt). ## Systemarchitektur (Postgres / Oqtane / Nginx) -In diesem Kapitel erkläre ich wie die ausgewählten Komponenten zusammenspielen. Wir verwenden NginX als Reverse Proxy, welcher bei uns die SSL Terminierung macht. Das Zertifikat, welches verwendet wird, wird von Let's Encrypt bereit gestellt und mitels HTTP-Challanges und dem Certbot auf dem Server aktualisiert und verwaltet. Oqtane selber läuft als Systemd-Service im Kestrel Backend. Kestrel ist ein kleiner Webserver, welcher in das ASP.NET Core Framework eingebaut worden ist. Oqtane (bzw. der ASP.NET Core Server "Kestrel") hört auf der Loopback IP und Port 5000. Damit ist Oqtane nur durch NginX erreichbar. PostgreSQL ist die Datenbank in dem System: Sie hört wieder auf der Loopback IP und Port 5432. +In diesem Kapitel erkläre ich wie die ausgewählten Komponenten zusammenspielen. Wir verwenden NginX als Reverse Proxy, welcher bei uns die SSL Terminierung macht. Das Zertifikat, welches verwendet wird, wird von Let's Encrypt bereit gestellt und mittels HTTP-Challenges und dem Certbot auf dem Server aktualisiert und verwaltet. Oqtane selber läuft als Systemd-Service im Kestrel Backend. Kestrel ist ein kleiner Webserver, welcher in das ASP.NET Core Framework eingebaut worden ist. Oqtane (bzw. der ASP.NET Core Server "Kestrel") hört auf der Loopback IP und Port 5000. Damit ist Oqtane nur durch NginX erreichbar. PostgreSQL ist die Datenbank in dem System: Sie hört wieder auf der Loopback IP und Port 5432. ```mermaid architecture-beta @@ -91,21 +90,21 @@ architecture-beta oqtane:R <--> L:db ``` -Zusätzlich gab es einen Administrationszugang zu den Servern, welcher über SSH möglich war. Dieser wurde für die Installation und Konfiguration der einzelnen Komponenten verwendet. Bei Hetzner war dieser Zugang nur über eine Wireguard VPN erreichbar. Bei der Schule war dieser Zugang direkt (über einen Hight-Port) möglich. Und bei LiveDesign war dieser Zugang wieder über eine VPN geregelt. Anfänglich mit SSL VPN, später mit einem IPSEC / Strongswan. +Zusätzlich gab es einen Administrationszugang zu den Servern, welcher über SSH möglich war. Dieser wurde für die Installation und Konfiguration der einzelnen Komponenten verwendet. Bei Hetzner war dieser Zugang nur über eine Wireguard VPN erreichbar. Bei dem Schulserver war dieser Zugang direkt (über einen Hight-Port) möglich. Und bei LiveDesign war dieser Zugang wieder über eine VPN geregelt. Anfänglich mit SSL VPN, später mit einem IPSEC / Strongswan. ## Entwicklung mit ASP.NET (Was ist Blazor? / Was ist Razor? / Kestrel) ### Blazor [^7] -Blazor ist ein kostenloses und quelloffenes Web-Framework, welches es Möglich macht, Benutzeroberflächen für Web-Browser basierend auf C# and HTML zu erstellen. Es wird von Microsoft als teil des ASP.NET Core Frameworks entwickelt. +Blazor ist ein kostenloses und quelloffenes Web-Framework, welches es möglich macht Benutzeroberflächen für Web-Browser, basierend auf C# and HTML, zu erstellen. Es wird von Microsoft als teil des ASP.NET Core Frameworks entwickelt. Blazor hat mehrere Hosting-Modelle: -- Blazor Web App: Hier wird die Web App als Teil einer ASP.NET Core Anwendung bereitgestellt. Hier gibt es mehrere Render Modi: - - Static Server: Die Komponente wird serverseitig "gerenderet" und besitzt keine Interaktivität. Das istder Default `RenderMode` - - Interative Server: Die Komponente wird serverseitig "gerendert", diesmal ist sie jedoch interaktiv. Das bedeutet: Man kann mithilfe von C# den Zustand der Seite dynamisch bearbeiten. Diese Zustandsänderungen werden serverseitig bearbeitet. Hierbei kommunizieren Server und Client mithilfe von SignalR über WebSockets miteinander. - - Interactive WebAssembly: Die Komponente wird clientseitig, also im Browser, "gerendert". Damit der Blazor C# Code auch im Browser ausgeführt werden kann wird dieser in WebAssembly kompiliert. +- Blazor Web App: Hier wird die Web App als Teil einer ASP.NET Core Anwendung bereitgestellt. Dabei gibt es mehrere Render Modi: + - Static Server: Die Komponente wird serverseitig gerendert und besitzt keine Interaktivität. Es ist der standardmäßige `RenderMode` + - Interactive Server: Die Komponente wird serverseitig gerendert, diesmal ist sie jedoch interaktiv. Das bedeutet, man kann mithilfe von C# den Zustand der Seite dynamisch bearbeiten. Diese Zustandsänderungen werden serverseitig bearbeitet. Hierbei kommunizieren Server und Client mithilfe von SignalR über WebSockets miteinander. + - Interactive WebAssembly: Die Komponente wird clientseitig, also im Browser, gerendert. Damit der Blazor C# Code auch im Browser ausgeführt werden kann, wird dieser in WebAssembly kompiliert. - Interactive Auto: Im `Interactive Auto` Modul wird bei dem initialen Besuch der Website der `Interactive Server` Modus gewählt und im Hintergrund wird der WebAssembly-Build heruntergeladen, damit bei weiteren Besuchen der Seite der `Interactive WebAssembly` Modus gewählt werden kann. -- Hybrid: Dieser Modus ist der einzige, welcher nicht innerhalb einer Blazor Web App läuft, sondern in einem WebView einer Nativen App. Dabei wird innerhalb des Mutterprozesses, ganz ohne WebServer. Das ganze Funktioniert in WPF und WinForms Apps und in nativen mobilen Apps für Android und iOS mithilfe von .NET MAUI. +- Hybrid: Dieser Modus ist der Einzige, welcher nicht innerhalb einer Blazor Web App läuft, sondern in einem WebView in einer Nativen App. Dabei wird innerhalb des Mutterprozesses, ganz ohne WebServer, der C# und Razor-Code ausgeführt. Das Ganze funktioniert in WPF und WinForms Apps und in nativen mobilen Apps für Android und iOS mithilfe von .NET MAUI. -Razor-Komponenten (in dieser Arbeit, sowie Umgangssprachlich, auch oft nur Komponenten genannt) sind der Grundbaustein für Blazor Web Apps. Sie bestehen aus HTML, welches mit der Verwendung von inline C# beeinflusst werden kann. Das Blazor stellt sicher, dass das gerenderte Markup aktualisiert wird, wenn sicher der Status der Komponente ändert. Dieser Code kann entweder vollständig in einer .razor Dateil liegen, oder in einer seperaten Code-Behind-Datei und der benutzer einer partiellen Klasse. Inline C# Code wird mithilfe von dem `@`- Zeichen markiert. Hier ist ein Beispiel für einen einfachen Counter: +Razor-Komponenten (in dieser Arbeit, sowie umgangssprachlich, auch oft nur Komponenten genannt) sind der Grundbaustein für Blazor Web Apps. Sie bestehen aus HTML, welches mit der Verwendung von inline C# beeinflusst werden kann. Das Blazor stellt sicher, dass das gerenderte Markup aktualisiert wird, wenn sich der Status der Komponente ändert. Dieser Code kann entweder vollständig in einer .razor Datei liegen, oder in einer seperaten Code-Behind-Datei. Inline C# Code wird mithilfe von `@`- Zeichen markiert. Hier ist ein Beispiel für einen einfachen Counter: ```razor

Counter

@@ -125,24 +124,24 @@ Razor-Komponenten (in dieser Arbeit, sowie Umgangssprachlich, auch oft nur Kompo } ``` -Mit`@count` in Zeile 3 wird der Wert der Variablen count in den `

` Tag mit eingebaut. Mit `@onclick="Increment"` in Zeile 5 wird die onclick Property vom `