diub-Dokumentation

Inhalt

Titel


1 Pragmati

1.1 Regeln

1.1.1 Abhängigkeiten der Bibliotheken

Database │ Log │ │ Unmanaged │ │ │ x86 ●── │ ─ │ ─ │ ─ SQLite3 │ │ ●── ●── │ ─ Types │ │ ○ ─ ○ ─ │ ─ ●── Interfaces │ │ ●── ○ ─ │ ─ ●── │ ─ Generics │ │ ●── ●── │ ─ ●── │ ─ │ ─ Sys │ ●── ○ ─ ○ ─ │ ─ ●── ●── ●── │ ─ Dispatcher │ ●── ●── ○ ─ │ ─ ●── ○ ─ ●── │ ─ ●── Serializer │ ●── ●── ●── │ ─ ●── ●── ●── ●── ●── │ ─ Class ●── ●── ○ ─ ○ ─ ●── ●── ○ ─ ●── ○ ─ ○ ─ ●── ●── SeOSQLite3 │ ●── ●── ●── │ ─ ●── ●── ●── ○ ─ ●── │ ─ ●── │ ─ IO │ ○ ─ ○ ─ ○ ─ │ ─ ○ ─ ○ ─ ○ ─ ○ ─ ○ ─ │ ─ ○ ─ │ ─ ●── diub.AlphaVSS │ ●── ○ ─ ●── │ ─ ●── ○ ─ ○ ─ ○ ─ ○ ─ │ ─ ○ ─ │ ─ ●── │ ─ FTP │ ●── ○ ─ ●── │ ─ ●── ○ ─ ●── ○ ─ ○ ─ │ ─ ○ ─ │ ─ ●── │ ─ │ ─ WebDav ●── ●── ●── ○ ─ │ ─ ●── ●── ●── ○ ─ ○ ─ ●── ●── │ ─ ●── │ ─ │ ─ │ ─ PersistentIndex ●── ●── ●── ●── ●── ●── ●── ●── ●── ●── ●── ●── ●── ●── │ ─ │ ─ │ ─ ●── diub

1.1.2 Debug-Informationen

#if DEBUG [DebuggerDisplay ("{DebuggerDisplay(),nq}")] #endif public class Example : IComparer<Object> { #if DEBUG /// <summary> /// Für die Ausgabe von "Text" im Debugger /// </summary> /// <returns></returns> public string DebuggerDisplay () { Text text; text = new Text (); text.AppendDebuggerDisplay (nameof (Date), ToString (WorldRegions.SystemDefault)); return text.ToString (); } #endif }

1.1.3 Ausnahmen unterdrücken

Wenn nur User-Code vom Debugger behandelt wird (Standardverhalten) kann mit diesem Funktions-Attribut ein Anhalten unterdrückt werden.

[System.Diagnostics.DebuggerNonUserCode] void Test () { try{ ... } catch(Exception) { } }

1.1.4 Property ohne Standardwert

Für Designer unsichtbar machen

[Browsable (false), EditorBrowsable (EditorBrowsableState.Never)]

Nur Lesen

[ReadOnlyAttribute (true)]

1.1.5 Multiple Rückgabe-Werte

CommonStatus

Der Status ist immer der erste Rückgabewert.

using diub.Universal; CommonStatus status; (status, setting) = Func (...);

1.1.6 Build Properties

https://docs.microsoft.com/de-de/dotnet/csharp/language-reference/configure-language-version

ProjektDatei ergänzen

<PropertyGroup> <Deterministic>false</Deterministic> </PropertyGroup>

Datei: Directory.Build.props

Im Projekt-Verzeichnis ablegen.

<Project> <PropertyGroup> <LangVersion>10</LangVersion> <Deterministic>false</Deterministic> </PropertyGroup> </Project>

1.2 Initialisierung

1.2.1 Konstruktor

InitializeComponent (); if (Setting.Designtime) return; // Öffnet den Dialog impliziet. StartUpDialog.Progress = 0; Setting.Init (this, App.DisplayButtons.None); // Icon aus PNG this.Icon = global::ConcatAudio.Properties.Resources.ConcatAudio.ToIcon (); Credits.Icon = this.Icon; Text = Credits.Copyright;

1.2.2 Load-Ereignis

Laufzeitsicherung

if (Setting.Designtime) return; StartUpDialog.Progress = 5;

Persistenzen

Persistence.Initialize ();

Projektverwaltung mit eigenem Format

// siehe auch ProjectHandling project = new ProjectHandling<ProjType> (Firm.ExtSetSave) { FileFormat = FileFormats.Documenter, NewFunction = null, OpenFunction = OpenFile, SaveFunction = FileSaveAs, SaveAsFunction = FileSaveAs, UpdateRecentUsed = UpdateRecentUsed };

Projektverwaltung mit Standard-Format

//Projektverwaltung // siehe auch ProjectHandling project = new ProjectHandling<ProjType> (); // Menü & Toolstrip initialisieren project.InitMenuCallbacks (MenuFileNew, MenuFileOpen, MenuFileSave, MenuFileSaveAs, MenuFileRecentUsed); project.InitToolstripCallbacks (ToolFileNew, ToolFileOpen, ToolFileSave, ToolFileSaveAs); // Optional, falls Aktionen nach Öffnen oder Speichern notwendig sind project.OpenDone += OpenDone; project.SaveDone += SaveDone;

Ein Default-Projekt als Datei anlegen und Öffnen

private ProjectHandling<ProjType> project = new ProjectHandling<ProjType>(); if (!File.FileExists (PathFilename)) project.CreateProjectFile ( new RecentUsedItem (PathFilename, FileFormats.XML) ); else project.OpenProject ( new RecentUsedItem (PathFilename, FileFormats.XML), this );

Dann Verlauf der zuletzt verwendeten Dateien

Persistence.RecentUsed.InitRecentUsed ( MenuFileLastUsed, new EventHandler (project.MenuFileRecentUsed_Click) );

Logger

Logger.CleanUpOutdatedLogs (); Logger.Write (MsgLogLevel.System, "Load", "Start initiated.");

Sprache & Menüs erweitern

// Sprachen initialsieren Language.Init ("de,en,it", Persistence.LanguageInfo.MainId); // Dialoge anpassen Strip.BuildOptionsMenu (this, Menue, null, xKeys.NoName, true); Strip.BuildHelpMenu (this, MenuStrip); // Sprache darstellen Language.Paint (this);

Aktualisieren-Menü/-Schaltfläche

Strip.BuildUpdateMenu (this); Strip.BuildUpdateTool (this);

Dateiendung registrieren

string RegisterFiletypeId = "diub.CSVeditor2x"; RegisterFiletype.RegisterAs (RegisterFiletypeId, "csv");

Hotkeys

// Bindet den 'HotkeyMethodHandler' in die Tastaturbehandlung ein. // Sorgt für die Prüfung auf 'Enabled' des zugehörigen Steuerelements!! HotkeyMethodHandler.ExamineMethods (this); // Neu setzten der Zuordnungen aus einer vorherigen Sicherung. HotkeyMethodHandler.UpdateMethods (Vars.app_options.Hotkeys);

Initialisierungen des Programms

// zum Beispiel Listen find_items = new TimedList<string> ("FindItems", 50); replace_items = new TimedList<string> ("ReplaceItems", 50);

Skalierung

ScalePrefix ();

1.2.3 AppOptions

Zum persistenten Speichern von Optionen (Zustands-Variablen) die das ganze Programm betreffen.

// Beispiel-Klasse public class AppOptions : AppOptionsFrame<AppOptions> { public string LastSourcePath = null; } // Die Optionen wieder einlesen _app_options = AppOptions.Load (); // Die Optionen sichern (zur Verwendung im Close-Ereignis) _app_options.Store ();

1.2.4 Shown-Ereignis

Laufzeitsicherung

if (Setting.Designtime) return; StartUpDialog.Progress = 60;

Skalierung und Position

AsyncScaleRestorePosition ( FormAndControls.FormResizeMode.Enabled, ShownDone ); private void ShownDone (object sender, EventArgs e) { // Schließt den Dialog impliziet StartUpDialog.Progress = 100; }

Öffnen bei Programm-Start via Parameter

RecentUsedItem rui; string [] args = Environment.GetCommandLineArgs (); if (args.Length > 1) { rui = new RecentUsedItem (args [1], FileFormats. ...); project.OpenProject (rui, this); }

Ressource freigeben

// Geschieht bei 'SyncScaleRestorePosition' und 'AsyncScaleRestorePosition' impliziet Persistence.ReleaseSettings ();

1.2.5 Handling

1.2.5.1 Project OpenDone

Titel aktualisieren

Credits.UsageInfo = _project.UsedFilename;

1.3 Innereien

1.3.1 Threading

Eine Übersicht findet sich unter: https://learn.microsoft.com/de-de/dotnet/standard/threading/overview-of-synchronization-primitives

Mutex (Mutual Exlusive)

Für exklusiven Zugriff: lässt immer nur einen einzelnen Thread zur Zeit aktiv werden; gegenseitige Ausschließlichkeit.

  • WaitOne
    Zugriff anfordern
  • ReleaseMutex
    Zugriff freigeben

Semaphore / SemaphoreSlim

Zur Sperrung bzw. gleichzeitigen Nutzung durch eine definierte, maximale Anzahl von Threads. Dabei werden, falls mehr Anforderungen gestellt werden als maximal erlaubt, die zusätzlichen Threads suspendiert. Sie werden nacheinander freigegeben, sobald die maximale Anzahl unterschritten wird.

  • SemaphoreSlim
    ist nur im erzeugenden Programm sichtbar. Erzwingt keine Thread- oder Task-Identität; ein Release kann auch aus einem (anderen) Thread ohne Zugriff erfolgen!
  • Semaphore
    (mit Namen) ist Prozess-übergreifend sichtbar. Erzwingt die Thread- oder Task-Identität; ein Release kann nur aus einem Thread mit Zugriff - durch Wait angefordert und erhalten - erfolgen!

Falls Zähler gewünscht werden, siehe xSemaphore.

// MaxCount = maxmale Anzahl gleichzeitiger Zugriffe // FreeOnStart = zum Beginn die Anzahl der verfügbaren Zugriffe Semaphore sema = new Semaphore(FreeOnStart, MaxCount);

  • WaitOne
    Fordert de Zugriff an.
  • Release
    Es wird ein einzelner Zugriff freigegeben.
  • Release (n)
    Es werden n Zugriffe freigegeben.

ManualResetEvent / ManualResetEventSlim

Zur manuellen Freigabe aller angeforderten Zugriffe. Die Sperrung erfolgt ebenfalls manuell!

Hinweis: nicht EventWaitHandle benutzten !

  • ManualResetEventSlim
    Wartet zu Beginn als Zeitschleife (Sleep) ohne Wait-Handle. Wechselt bei längeren Wartezeiten automatisch auf ein Wait-Handle. Bietet bei sehr kurzen Wartezeiten (leichte) Vorteile bzgl. der Kosten.
  • ManualResetEvent
    Wartet auf Basis eines Wait-Handle.

Zustände:

  • Non-signaled / Nicht-signalisiert
    = False
  • Signaled / Signalisiert
    = True

// False = Nicht signalisiert → Zugriffe werden aufgehalten ManualResetEvent mre = new ManualResetEvent(false);

  • WaitOne
    Zugriff anfordern
  • Set
    auf True setzen, alle Zugriffe erlauben, bis Reset aufgerufen wird.
  • Reset
    auf False setzten, Zugriffe blockieren, bis Set aufgerufen wird.

AutoResetEvent

Zur manuellen Freigabe aller angeforderten Zugriffe. Die Sperrung erfolgt jedoch automatisch sofort (nach Freigabe der bis dahin aufgeaufenen Zugriffe).

Hinweis: nicht EventWaitHandle benutzten !

  • Non-signaled / Nicht-signalisiert
    = False
  • Signaled / Signalisiert
    = True

// False = Nicht signalisiert → Zugriffe werden aufgehalten AutoResetEvent are = new AutoResetEvent (false);

  • WaitOne
    Zugriff anfordern
  • Set
    auf True setzen, alle Zugriffe erlauben, bis Reset aufgerufen wird.
  • Reset
    erfolgt automatisch, darf nicht manuell aufgerufen werden.

Monitor

Hinweis: in normalen Szenarien sollte statt Monitor besser Semaphore oder Mutex benutzt werden.

  • Wait
    Zugriff anfordern
  • TryEnter
    Zugriff anfordern mit Zeitbeschränkung und Rückmeldung, ob der Zugriff gewährt wurde.
  • IsEntered
    True: der aufrufende Thread ist derjenige mit Zugriff.
  • Exit
    Zugriff freigeben
  • Pulse
    reichlich exotisch: der Thread mit Zugriff gibt damit einen wartenden (Zugriff anfordernden) Thread frei. Wartet kein Thread, tut sich gar nichts.
  • PulseAll
    reichlich exotisch: der Thread mit Zugriff gibt damit alle wartenden (Zugriff anfordernden) Threads frei. Wartet kein Thread, tut sich gar nichts.

1.3.2 Ticker

Minimal-Version eines eigenen Tickers.

private ManualResetEvent signal = new ManualResetEvent (false); public void Start () { signal.Reset(); (new Thread (Loop)).Start (); } public void Stop () { signal.Set (); } private void Loop () { do { // Tick...tick...tick while (!signal.WaitOne (Interval); } }

1.3.3 Ereignisse

Delegat definieren

public delegate void DCmdKeyPressed (object sender, CmdKeyEventArgs e);

Event anlegen - sichtbar im Designer

[Category ("_diub")] [DesignerSerializationVisibility (DesignerSerializationVisibility.Visible)] [EditorBrowsable (EditorBrowsableState.Always)] [Browsable (true)] [Bindable (true)] [DefaultValue (null)] public event DCmdKeyPressed XKeyPressed;

Aufrufen

XKeyPressed?.Invoke (this, e);

1.3.4 *.bak

// einfache *.bak Datei status = File.BackupThisFile (RUI.PathFilename); // Dateiname-[Datum-Zeit].Ext.Bak status = File.CreateTimedBackupFile (RUI.PathFilename, null, Vars.AppOptions.CommonOptions.GenerationBackups);

1.3.5 xUserControl

Hotkey Zuweisung

Hotkey = xKeys.Alt | xKeys.E;