Architecture

When designing a Windows Forms application, you have several architectural patterns to choose from. The common ones are:

Model-View-Controller (MVC):

• Description: MVC separates the application into three components:
  • Model: Represents the data and business logic.
  • View: Handles the presentation and user interface.
  • Controller: Manages user input and communicates between the Model and View.
• Pros:
  • Clear separation of concerns.
  • Reusable components.
  • Supports unit testing.
• Cons:
  • Can become complex for small applications.
  • Requires careful design to avoid tight coupling.
• Use Case: Suitable for medium to large applications with complex interactions.

Clean Architecture:

• Description: Clean Architecture emphasizes separation of concerns and independence from external frameworks.
• Entities: Represent core business logic.
• Use Cases (Interactors): Application-specific business rules.
• Interfaces (Gateways): Define external interfaces (e.g., database, UI).
  • Frameworks & Drivers: External frameworks and tools (e.g., Windows Forms, databases).
  • Pros:
    • Highly modular and testable.
    • Adaptable to changes in external frameworks.
    • Focuses on business logic.
  • Cons:
    • Initial setup complexity.
    • May be overkill for small projects.
  • Use Case: Suitable for large, long-lived applications with evolving requirements.

Roadmap

Umbau auf .Net 8

AspNetCore + Webassembly

Der mobile Client wird als Testprojekt mit AspNetCore für REST und Webassembly für den Client aufgesetzt

Aspire / Webassembly / Blazor

Ein Video dazu. Werd DTN für IPM fertig machen und dann ein entsprechendes Projekt fuer die weitere Diskussion als Beispiel aufsetzen. Ist allerdings erst in preview … das sollte man evtl. abwarten

Avalonia

Zurückgestellt Mit dem Avalonia framework könnte man einfache Clients wie e.g. die Spreadsheets für die Module bereitstellen. Das waere vorallem für Desktop Apps. Ansonsten würde Blazor wohl die einfachere Herangehensweise sein weil es über den Browser alles abdeckt. Sollte auf jeden Fall in separatem Verzeichnis entwickelt werden weil es Einstellungen vornimmt die mit anderen Frameworks nicht kompatibel sind. Ist allerdings noch auf .Net 7. Wird wohl noch ein bisschen dauern bis das fuer .Net 8 nachgezogen ist.

• Alternativen:
  • MAUI - das unterstützt aber kein Linux und ist was ich gesehen hab auch nicht so performant
  • UNO - hab ich noch nicht genauer angesehen. Wohl ähnlich zu Avalonia aber nicht so verbreitet etc.

Cocona

Für CLI Clients

Beispiele für Diagramme

timeline
    title Diversity Workbench - timeline
    2023-11-15 : Einstieg in Version 8
    2023-12-15 : IPM 
                : WinForm Client 2023-11-15
                : WASM-Client 2023-12-15
    2023-12-20 : WASM-Client 
               : Preview 2024-01-20
               : Workshop 2014-03-22
    2024-02-15 : WASM-Client for DC

gantt
        dateFormat  YYYY-MM-DD
        title IPM
        section IPM Winforms Client
        Completed task            :done,    des1, 2024-01-06,2024-01-08
        Active task               :active,  des2, 2024-01-09, 3d
        Future task               :         des3, after des2, 5d
        Future task2              :         des4, after des3, 5d
        section IPM WASM Client
        Completed task in the critical line :crit, done, 2024-01-06,24h
        Implement parser and jison          :crit, done, after des1, 2d
        Create tests for parser             :crit, active, 3d
        Future task in critical line        :crit, 5d
        Create tests for renderer           :2d
        Add to Mermaid                      :1d

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

HUGO

Installation of HUGO

• Installation von HUGO: https://gohugo.io/getting-started/quick-start/
  • als Theme https://themes.gohugo.io/themes/hugo-theme-relearn/
    • Befehl hierfür: git submodule add https://github.com/McShelby/hugo-theme-relearn.git themes/relearn

Update des Themes

um das Theme auf die letzte Version zu bringen kann man den Befehl git submodule update --remote --merge themes/relearn verwenden

Übersetzung des Bestands an html

• Übersetzung der *.html Seiten mit pandoc in *.md
• Aufbau einer Ordnerstruktur die dem Index der chm Datei entspricht
• Das Basisdokument der Ordner wird in die Ordner verschoben und in _index.md umbenannt
  • Dort im Frontmatter steht der Titel der im Menü angezeigt wird, e.g.:

    --- 
    title: Installation 
    ---  

Überarbeitung der md Dateien

• Korrektur der Bildverweise
  • Ordner mit den Bildern in den Ordner static kopieren
  • von e.g. ![](img/...) in ![](/manual/dwb/img/...)
  • ACHTUNG - Case sensitiv. Namen müssen stimmen
  • Icons gegebenenfalls freistellen für Darkmode
• Entfernung aller störenden Formatierungsangaben
• Entfernung der Kopfzeile (Überschrift wird von HUGO automatisch erzeugt)
• Korrektur der internen Verweise
  • ändern von [![](/manual/dwb/img/VideoDE.svg?classes=inline)](http://media.snsb.info/Tutorials/dwb/Editing/OeffentlicheKontaktdaten.webm) zu [![Video starten](/manual/dwb/img/VideoDE.svg?height=20px&lightbox=false&classes=inline)](http://media.snsb.info/Tutorials/dwb/Editing/OeffentlicheKontaktdaten.webm)
    • ansonsten wird das Bild gezeigt statt das Video zu starten
  • ändern von

    [Contact](Contact.htm)

    zu e.g.

    [Contact](/manual/dwb/editingdata/contact)

  • Wenn als Basisadresse in hugo.toml etwas angegeben wurde, e.g. baseURL = "http://www.diversityworkbench.de/manual/dwb/" dann muss diese auch für Verweise innerhalb der Files verwendet werden.
    • e.g. Bildverweise ![](/manual/dwb/img/IcoFeedback.gif?classes=inline)
    • Dateiverweise [Anmelden](/manual/dwb/database)
    • HUGO relearn erzeugt für Überschriften Anker die man ansteuern kann, e.g. kann man ### Table **AgentResource** über die Adresse /manual/dwb/database/database/#table-agentresource erreichen. Ein Index Eintrag dafür wäre e.g. [AgentResource](/manual/dwb/database/database/#table-agentresource). ACHTUNG - Case sensitiv: ### Table **AgentResource** wird in #table-agentresource übersetzt
  • Kommentare starten mit # ohne folgendes Leerzeichen

Frontmatter

You can change the frontmatter to a default using the documentation tool

• Steht am Anfang der Datei und ist bei yaml durch --- oben und unten abgegrenzt, e.g.

  ---
  title: Login administration
  linktitle: Logins
  weight: 5
  menuPre: <img src="/manual/dwb/img/Documentation.svg" height="20">&nbsp;
  alwaysopen: false
  ---

• Seiten die noch in Entwicklung sind kann man mit draft: true im Frontmatter markieren. Diese werden dann nicht in die Ausgabe übernommen
• Der Titel wird mit title: Login administration angegeben. Dieser erscheint dann auch in der Seite als Überschrift
• Der Text im Menü kann abweichend definiert werden mit linktitle: Logins. Ansonsten erscheit der Titel im Menü
• Die Reihenfolge im Menü kann mit weight: 5 angegeben werden. Ansonsten wird alphabetisch sortiert
• Ein Logo kann man mit menuPre: <img src="/manual/dwb/img/LinkedServer.svg" height="20">&nbsp; hinzufügen. Das Bild sollte *.svg sein
• Wenn das Untermenue erst beim Anwählen geöffnet werden soll: alwaysopen: false

Bilder

You can adapt the images to a default using the documentation tool

• Icons die e.g. in den Text integriert werden sollen, müssen folgedermassen eingebaut werden:
  • ![](/manual/dwb/img/Database.svg?height=20px&lightbox=false&classes=inline)
• Die Bilder am Anfang der Seite werde wie folgt eingebaut:
  • ![](/manual/dwb/img/LinkedServer.svg?height=10vw&lightbox=false)

mit px wird das Bild mitgezoomt, bei vw bleibt es gleich gross

• noch nicht zu svg konvertierte Bilder die im Fliesstest erscheinen sollen werden wie folgt eingebunden:
  • ![](/manual/dwb/diversitycollection/IcoDelete.gif?classes=inline&lightbox=false)
• sonstige Bilder mit
  • ![](/manual/dwb/diversitycollection/IcoDelete.gif)

mit der Angabe ...lightbox=false wird verhindert, dass ein Bild beim Anklicken mit der Maus geöffnet wird. Dies sollte bei Bildern die nicht nach svg konvertiert wurden und nicht im Fliesstext erscheinen nicht verwendet werden, damit der User bei kleinen Bildern diese in Originalauflösung betrachten kann. Unten 2 Beispiele

![](/manual/dwb/diversitycollection/IcoDelete.gif?classes=inline&lightbox=false)

![](/manual/dwb/diversitycollection/IcoDelete.gif?classes=inline)

Links innerhalb des Manuals

Für Links innerhalb des Manuals kann man shortcodes verwenden. Dafür entweder auf den Namen der Datei oder auf Links von Überschriften (ab ##) verwenden. Diese müssen innerhalb des Manuals eindeutig sein. Für Header als erstes Zeichen # dann Überschrift und alles lower case und Leerzeichen werden durch - ersetzt. Beispiel:

## Main form of diversityexsiccatae

wird zu sofern es sich in der gleichen Datei befindet: {{ % relref "#main-form-of-diversityexsiccatae" % }}

Für Links ausserhalb der Datei werden Verweise unter Einschluss des Dateinamens verwendet:

Verweis auf ein Kapitel innerhalb einer Datei {{ < relref "diversityexsiccatae#main-form-of-diversityexsiccatae" > }}

bzw. nur auf die Datei {{ < relref "diversityexsiccatae" > }}

Leerzeichen zwischen {{ % und % }} entfernen

Links auf das Manual

Von ausserhalb kann e.g. eine Überschrift mit https://www.diversityworkbench.de/manual/dwb/modules/diversityexsiccatae/index.html#main-form-of-diversityexsiccatae aufgerufen werden. Diese können direkt aus dem Manual kopiert werden.

Logo

• hierfür das Logo in den Ordner static kopieren
• im Ordner layouts einen Ordner partials anlegen
• dort eine Datei logo.html anlegen
  • in dieser auf das Logo verweisen e.g.:

    <h4><b>DiversityAgents</b></h4>
    <img src="/DA_4D.svg">

Menu- Fusseintrag

• in static - layouts - partials die Datei menu-footer.html anlegen und anpassen

favicon

Im Ordner static den Ordner images anlegen Datei favicon.ico in der Ordner static/images kopieren

Einschliessen von Dateien

Das Verzeichnis templates enthält Dateien die in andere Dateien über eine shortcode eingeschlossen werden können, e.g.:  {{% include file="templates/template_workbench.md" %}} Diese Dateien dürfen kein frontmatter enthalten. Shortcodes müssen überprüft werden, da diese in der Regel nicht ausgewertet werden.

ER-Diagramm

dieses kann als Mermaid eingebaut werden, e.g.

---
title: ER-Diagram
---
graph LR;
    A[Agent] --> B[AgentContact<br/>Kontaktdaten der Agents]
    A --> C[AgentReference]
    A --> D[AgentIdentifier]
    A --> E[AgentResource]
    A --> F[AgentExternalID]
    G[AgentExternalDatabase] --> F[AgentExternalID]

soll das Diagramm zoombar sein wird die Version 5.23 des Themes benoetigt. Ausserdem kann der Parameter nur für die Shortcode Version angegeben werden, nicht für die Codefences:

{{ < mermaid align="center" zoom="true" > }}
... 
(remove space between {{ and < resp > and }} in header and footer for correct code)
...
{{ < /mermaid > }}

Anpassung des Themes

• es werden 2 eigene Themes bereitgestellt

  • im Verzeichnes
    • themes
      • relearn
        • static
          • css:
          • theme-dwb-dark.css
          • theme-dwb.css

  diese an DWB Anforderungen anpassen

  • in \themes\relearn\static\css\theme.css

    #body img.inline {
        display: inline !important;
        margin: 0 !important;
        vertical-align: middle;
        /* vertical-align: bottom; */
    }

  • in \themes\relearn\static\css\theme-dwb.css

    /*--MENU-HEADER-BG-color: rgba( 28, 144, 243, 1 );*/ /* Background color of menu header */
    --MENU-HEADER-BG-color: rgba( 220, 220, 220, 1 ); /* Background color of menu header */
    --MENU-HEADER-BORDER-color: rgba( 51, 161, 255, 1 ); /*Color of menu header border */
    
    --MENU-SEARCH-color: rgba( 255, 255, 255, 1 ); /* Color of search field text */
    /*--MENU-SEARCH-BG-color: rgba( 22, 122, 208, 1 );*/ /* Search field background color (by default borders + icons) */
    --MENU-SEARCH-BG-color: rgba( 90, 90, 90, 1 ); /* Search field background color (by default borders + icons) */
    /*--MENU-SEARCH-BORDER-color: rgba( 51, 161, 255, 1 );*/ /* Override search field border color */
    --MENU-SEARCH-BORDER-color: rgba( 0, 0, 0, 1 ); /* Override search field border color */

Konfiguration - in hugo.toml:

```native
baseURL = "http://www.diversityworkbench.de/manual/dwb/"
languageCode = "en-us"
title = "DiversityAgents"
theme = "relearn"

[outputs]
    home = ["HTML", "RSS", "SEARCH", "SEARCHPAGE"]
    section = ["HTML", "RSS", "PRINT"]
    page = ["HTML", "RSS", "PRINT"]

[params]
    themeVariant = [ "auto", "dwb", "dwb-dark" ]
```

Start des Testservers:

• mit einem Terminal in das Verzeichnis des Projekts wechseln
• dort hugo server eingeben.
  • bei Problem mit Sonderzeichen: den Inhalt der Datei config.toml in hugo.toml kopieren und config.toml löschen (beide sollten wenn vorhanden UTF8 sein - werden manchmal als UTF16 angelegt - dieses dann nach UTF8 ändern)
    • Error: “…\diversityworkbench\hugo.toml:1:1”: unmarshal failed: toml: invalid character at start of key: ÿ
• Im Browser an die angegebene Adresse navigieren, e.g. localhost:1313
• Wenn als Basisadresse in hugo.toml etwas angegeben wurde, e.g. baseURL = "http://www.diversityworkbench.de/manual/dwb/" dann muss die passende Adresse eingeben werden also e.g. localhost:1313/manual/dwb/

github

ssh-key

To use this option you may have to install OpenSSH for Windows

To change the authentication mechanism to SSH keys in Visual Studio Code and GitHub, you need to follow these steps:

• Open the command line and change in your homedirectory if not already done cd %USERPROFILE%
• Generate an SSH key pair on your local machine using the command ssh-keygen -a3 -t ed25519 -C "your_email@example.com" -f .ssh/id_github.
  • In case you omit the -f option nameing the file where the key should be stored, you will be asked th enter the name of the file where the key should be stored e.g. id_github. Make shure not to overwrite existing keys.
• Next enter a passphrase (twice)
  • When you generate an SSH key pair, you have the option to add a passphrase to the private key. A passphrase is an extra layer of security that helps protect your private key from unauthorized access. If someone gains access to your private key, they can use it to authenticate as you and perform actions on your behalf. By adding a passphrase, you make it more difficult for someone to use your private key without your permission.
  • When you use an SSH key with a passphrase, you will be prompted to enter the passphrase every time you use the key. This can be inconvenient, but it ensures that only you can use the key to authenticate with remote servers. You can also use an SSH agent to store your passphrase so that you don’t have to enter it every time you use your key .
  • The location of your keys will be shown (e.g. id_github for the private key and id_github.pub for the public key) next to a fingerprint and a randomart image like

    +--[ED25519 256]--+
    |     ..   .+=.o  |
    |      .+ . o+*   |
    |    . +.. ooo.o  |
    |     +.B.+= =.o  |
    |      =+S=o* = o |
    |     . oo*= o o  |
    |      .  .       |
    |        . . o E  |
    |           o .   |
    +----[SHA256]-----+

• Add the public key to your GitHub account by navigating to your account settings, selecting “SSH and GPG keys”, and clicking “New SSH key”.
• Copy the contents of the public key file (usually ~/.ssh/id_rsa.pub) and paste it into the “Key” field on the GitHub website.
• In Visual Studio Code, open the Command Palette (press Ctrl+Shift+P on Windows) and search for Remote-SSH: Open SSH Configuration File.
  • You may need to install the extension Remote-SSH first
• Select the configuration file you want to edit and add the following lines:

  Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_rsa

• Save the file and close it.
• Open the Command Palette again and search for Remote-SSH: Connect to Host.
• Select the configuration file you just edited and wait for the connection to be established.
• You should now be able to use Git with SSH authentication in Visual Studio Code.