Registerkarte Methods

Bei den Methoden handelt es sich um Methoden im Sinne von .NET. Innerhalb der Methoden können Sie frei nach den Regeln von C# Code schreiben und mit den Properties der Component arbeiten. Die Methoden werden im ClassView-Registerkarte aufgelistet und sind an dem -Icon zu erkennen.

Neue Methoden anlegen / löschen

Mit dem Button (New) und dem Eintrag Public Method, Protected Method oder Method(override) aus dem sich öffnenden Kontextmenü können Sie eine neue Methode erzeugen. Mit Public Method und Protected Method wird eine leere Methode angelegt.

Mit Method(override) haben Sie die Möglichkeit, eine in einer Basis-Klasse definierte virtuelle Methode zu überschreiben. Es erscheint ein Auswahl-Dialog, der die verfügbaren Methoden anbietet. Wenn Sie einen Eintrag auswählen und mit OK bestätigen, wird eine neue Methode angelegt, deren Deklaration entsprechend vorbelegt ist.

In der ClassView-Registerkarte hat das Kontext-Menü der Methoden einen Eintrag Delete. Mit diesem Eintrag können Sie die Methode löschen.

Methoden bearbeiten

Um eine Methode zu öffnen, gibt es zwei Möglichkeiten:

• Auf der Registerkarte ClassView einen Doppelklick auf die gewünschte Methode.
• Auf der Registerkarte Method die gewünschte Methode in der Tabelle auswählen.

Auf der Registerkarte Method wird in dem großen Edit-Feld der Quellcode der Methode angezeigt, den Sie dort auch bearbeiten können.

Methoden in jeder Component / Collection

Im folgenden Abschnitt werden die Methoden beschrieben, die jede Component / Collection bereits als Voraussetzung mitbringt, da sie in der Component-Basisklasse DevFrameworkObjekt bzw. DevFrameworkObjektColl implementiert sind.

AcceptChanges( )

Verfügbar für Component / Collection.

public void AcceptChanges( )

Übernimmt alle Änderungen, indem es die OrgValues auf die PropertyValues und den Status auf Unchanged setzt. Es wird keine Datenbanktransaktion ausgeführt. Bei Collections führt diese Methode dazu, dass Objekte, deren Status Deleted ist, aus der Collection unwiderruflich entfernt werden.

AdoptValues()

Verfügbar für Component / Collection

Übernimmt alle Properties der übergebenen Component / Collection in die eigenen Properties. Von Unterobjekten wird eine Tiefen-Kopie (Clone) erzeugt.

void AdoptValues(IDevFrameworkBaseObject fromComponent)
void AdoptValues(IDevFrameworkBaseObject fromComponent, AdoptMode mode)
void AdoptValues(IDevFrameworkBaseObject fromComponent, AdoptDictionary dict)
void AdoptValues(IDevFrameworkBaseObject fromComponent, AdoptDictionary dict, AdoptMode mode)

Im Parameter fromComponent wird die Component übergeben, deren Properties übernommen werden sollen.

Über die Parameter dict und mode kann optional das Verhalten der Methode gesteuert werden. Siehe auch Kapitel Clone() und AdoptValues()

Clear()

Verfügbar für Collection.

public void Clear()

Reinitialisiert die Collection als leere Collection.

Clone()

Verfügbar für Component / Collection

Erzeugt eine Tiefen-Kopie der Component oder Collection und gibt diese zurück.

public IDevFrameworkBaseObject Clone()
public IDevFrameworkBaseObject Clone(AdoptMode mode)
public IDevFrameworkBaseObject Clone(AdoptDictionary dict)
public IDevFrameworkBaseObject Clone(AdoptDictionary dict, AdoptMode mode)

Über die Parameter dict und mode kann optional das Verhalten der Methode gesteuert werden. Siehe auch Kapitel Clone() und AdoptValues().

Delete( )

Verfügbar für Component / Collection.

Diese Methode setzt den Komponentenstatus auf Deleted. Die Komponente wird dabei aus der Collection entfernt. Damit auf dem Datasource ein physikalischer Delete ausgeführt wird, muss noch ein Save aufgerufen werden.

Diese Methode ist funktional identisch mit der Methode Remove().

public void Component.Delete()
Setzt den Komponentenstatus auf Deleted.
public void Collection.Delete()
Setzt den Komponentenstatus aller Components der Collection auf Deleted.
public void Collection.Delete(DevFrameworkObject obj)
Setzt den Komponentenstatus der übergebenen Component auf Deleted.
public void Collection.Delete(SelectedRowsCollection selectedRows)

Setzt den Komponentenstatus aller Komponenten, deren IDs in der SelectedRowsCollection enthalten sind, auf Deleted.

Load( )

Verfügbar für Component / Collection.

public int Load()

Lädt alle Datensätze aus der verknüpften Query.

public int Load(string loadCondition)

Lädt Datensätze entsprechend der Bedingung aus der Datenbank und liefert die Anzahl der gefundenen Datensätze zurück.

public int Load(string loadCondition, string OrderByClause)
public int Load(string loadCondition, string HavingClause, string OrderByClause)

Für das Anpassen der Load-Kriterien werden verschiedene Methoden zum Überschreiben angeboten:

• OnBeforeLoad( ) auf der Ebene der Component bzw. Collection.
• GlobalOnBeforeLoad( ) auf globaler Ebene.

LoadCount( )

Verfügbar an Component / Collection

public int LoadCount(string loadCondition)

Ermittelt die Anzahl der Datensätze für die übergebene Load-Condition. Der Zustand des Objektes bzw. der Collection bleibt dabei unverändert.

Save( )

Verfügbar für Component / Collection.

public void Save( )

Save speichert die Änderungen in die Daten-Datenbank.

Component.Save( )

Der Befehl läuft in folgenden Schritten ab:

CreateTransaction( )
OnBeforeSaveCustom( ) (Entrypoint)
OnBeforeSave() (Entrypoint)
GlobalOnBeforeSaveAction( ) (Entrypoint)
DeleteMarkedObjects()
Aktion auf der Datenbank.
AcceptChanges( )
OnAfterSave() (Entrypoint)
OnAfterSaveCustom( ) (Entrypoint)
Commit( )

Läuft etwas in einem der Entrypoints schief und es wird eine Exception geworfen, wird die gesamte Transaktion abgebrochen und Rollback( ) ausgeführt.

Es folgt eine Aufstellung, wie sich der Befehl bei den einzelnen Status verhält.

FrameworkComponentState.Unchanged Es wird keine Aktion auf der Datenbank ausgeführt. Die Entrypoints werden nur angestoßen, wenn EntryPoints.CallAllways übergeben wurde.

FrameworkComponentState.New Es wird ein Insert in die Daten-Datenbank gemacht. Es werden alle Daten in die OrgValue-Properties übertragen.

FrameworkComponentState.Changed Es wird ein Update auf die Daten-Datenbank gemacht. Es werden alle Daten in die OrgValue-Properties übertragen.

FrameworkComponentState.Deleted Es wird ein Delete auf die Daten-Datenbank gemacht. Ist die Component ein Eintrag in der Collection, wird sie aus dieser entfernt.

Collection.Save( ) Der Befehl läuft in folgenden Schritten ab:

CreateTransaction( )
OnBeforeSaveCustom( ) (Entrypoint)
OnBeforeSave( ) (Entrypoint)
Save( ) auf jedes Objekt in der Collection
OnAfterSave( ) (Entrypoint)
OnAfterSaveCustom( ) (Entrypoint)
Commit( )

Läuft etwas in einem der Entrypoints schief und es wird eine Exception geworfen, wird die gesamte Transaktion abgebrochen und Rollback( ) ausgeführt.

Warning

Ist der Status einer Component Unchanged, werden die Entry-Points der Save-Methode (OnBeforeSave, OnAfterSave, …) nicht aufgerufen, da der Save-Vorgang abgebrochen wird, und keine Transaktion stattfindet.

public void Save(SaveEntryPoints)

Diese Überladung der Methode ist dazu da, wenn die Entrypoints abgearbeitet werden sollen, obwohl der Save der Component auf Unchanged steht.

// Die Entrypoints werden immer ausgeführt
oCompoinet.Save( SaveEntryPoints.CallAllways )

// Die Entrypoints werden nur ausgeführt, wenn der Status nicht Unchanged ist.
oCompoinet.Save( SaveEntryPoints. CallOnlyIfChanged )

RollbackChanges( )

Verfügbar für Component / Collection.

public void RollbackChanges( )

Setzt alle PropertiesValues auf die OrgValues.

CreateTransaction( )

Verfügbar für Component / Collection.

public FrameworkDataTransaction CreateTransaction( )

Startet eine Transaktion. Weisen Sie der Komponente einen Datasource zu, damit eine Transaktion gestartet werden kann, da die Transaktion selbst an einen Datasource gebunden ist.

Gibt das Transaktionsobjekt zurück, sofern es erzeugt werden konnte. An diesem Transaktionsobjekt kann der Commit bzw. Rollback erfolgen. An geeigneter Stelle muss es mittels Dispose-Aufruf bzw. dem Ende eines using-Blocks abgeräumt werden.

Wenn die Transaktion aufgrund eines Fehlers nicht gestartet werden kann, wird eine Exception geworfen.

HasDbChanged( )

Verfügbar an DataComponent.

public bool HasDbChanged()

Damit kann einer RowVersionInvalidException zuvorgekommen werden. Mit der Methode ReloadData() können die Daten des Datensatzes neu eingelesen werden.

Gibt zurück, ob sich der Datensatz auf der Datenbank geändert hat. Diese Methode arbeitet sowohl mit der RowID-RowVersion-Logik als auch mit einer PK-RowVersion-Logik.

Wenn an einer Component die Save-Methode aufgerufen wird, prüft diese, ob der Datensatz in der Datenbank geändert wurde, um ein konkurrierendes Update zu verhindern. Wenn das zutrifft, dann wird eine RowVersionInvalidException geworfen und die Save-Aktion abgebrochen. Mit dieser Methode kann das im Vorfeld geprüft und ggf. ReloadData() ausgeführt werden.

ReloadData( )

Verfügbar an DataComponent.

public int ReloadData()

Diese Methode aktualisiert die Daten aus der Datenbank. Sie führt einen Load auf die Component aus und verwendet dabei die aktuellen Primary-Key-Informationen für die Suchbedingung. Wenn die Component nicht mit der RowID-RowVersion-Logik arbeitet, dann wird der logische Primary-Key verwendet.

Das ist z.B. sinnvoll, wenn mit der Methode HasDbChanged eine Änderung auf der Datenbank festgestellt wurde.

Zurückgegeben wird das Ergebnis der Load-Methode: 1 – erfolgreich eingelesen; 0 – es wurde nichts gelesen, weil der Datensatz z.B. nicht mehr existiert.

OnBeforeLoad( )

Verfügbar für Component / Collection mit einer Query.

Diese Methode kann überschrieben werden. Sie bietet auf Component-Ebene einen zentralen Einstiegspunkt, um vor einem Datenbank-Load die Load-Condition, die Having-Clause oder die Order-By-Clause zu erweitern oder anzupassen.

Data-Component:

protected virtual bool OnBeforeLoad(ref string loadCondition, ref string replacingHavingClause, ref string replacingOrderClause, bool fromCollection)

Sie wird aufgerufen, bevor an der Component / Collection ein Load() oder an der Component ein GetFetchNext() ausgeführt wird.

Der Aufruf erfolgt vor GlobalOnBeforeLoad( ).

Beim Aufruf aus der Collection wird im Parameter fromCollection true übergeben. So kann bei Bedarf entsprechend reagiert werden. Es ist jedoch empfehlenswert, die Load-Condition nur einmal zentral in der Component zu erweitern.

Der Aufruf folgt nach dem Aufruf der OnBeforeLoad-Method in der Collection.

Data-Collection:

protected virtual bool OnBeforeLoad(ref string loadCondition, ref string replacingHavingClause, ref string replacingOrderClause)

Sie wird aufgerufen, bevor an der Collection ein Load( ) ausgeführt wird.

Der Aufruf erfolgt vor GlobalOnBeforeLoad( ).

Nach dieser Methode ruft die Collection auch an der Component die Methode OnBeforeLoad() auf. Dazu wird temporär ein neues leeres Objekt erzeugt.

OnBeforeSave( )

Verfügbar für Component / Collection.

protected virtual bool OnBeforeSave()

Diese Methode kann in der Component / Collection überschrieben werden.

Siehe auch LoadCount()

Verfügbar an Component / Collection

public int LoadCount(string loadCondition)

Ermittelt die Anzahl der Datensätze für die übergebene Load-Condition. Der Zustand des Objektes bzw. der Collection bleibt dabei unverändert. Save( )

OnBeforeSaveCustom( )

Verfügbar für Component / Collection.

protected virtual bool OnBeforeSaveCustom()

Diese Methode kann in der Component / Collection überschrieben werden.

Siehe auch LoadCount()

Verfügbar an Component / Collection

public int LoadCount(string loadCondition)

Ermittelt die Anzahl der Datensätze für die übergebene Load-Condition. Der Zustand des Objektes bzw. der Collection bleibt dabei unverändert. Save( )

OnBeforeSaveAction( )

Verfügbar für Component.

protected virtual void OnBeforeSaveAction()

Diese Methode kann in der Component überschrieben werden. Standardmäßig ruft diese Methode this.Global.ocGlobal.GlobalOnBeforeSaveAction() auf.

Siehe auch LoadCount()

Verfügbar an Component / Collection

public int LoadCount(string loadCondition)

Ermittelt die Anzahl der Datensätze für die übergebene Load-Condition. Der Zustand des Objektes bzw. der Collection bleibt dabei unverändert. Save( )

OnAfterSave( )

Verfügbar für Component / Collection.

protected virtual void OnAfterSave()

Diese Methode kann in der Component / Collection überschrieben werden.

Wird nach dem Speichern aufgerufen.

Siehe auch LoadCount()

Verfügbar an Component / Collection

public int LoadCount(string loadCondition)

Ermittelt die Anzahl der Datensätze für die übergebene Load-Condition. Der Zustand des Objektes bzw. der Collection bleibt dabei unverändert. Save( )

OnAfterSaveCustom( )

Verfügbar für Component / Collection.

protected virtual void OnAfterSaveCustom()

Diese Methode kann in der Component / Collection überschrieben werden.

LoadCount( )

Verfügbar an Component / Collection

public int LoadCount(string loadCondition)

Ermittelt die Anzahl der Datensätze für die übergebene Load-Condition. Der Zustand des Objektes bzw. der Collection bleibt dabei unverändert. Save( )

OnAfterInit( )

Verfügbar für Component / Collection

protected virtual void OnAfterInit( )

Diese Methode kann in der Component / Collection überschrieben werden.

Sie wird aufgerufen, direkt nachdem die Component / Collection instanziiert wurde. Hier können Werte vorbelegt werden, die man ansonsten in einem Konstruktor setzen würde.

Warning

Innerhalb dieser Methode darf kein Load, Save oder sonst eine Datenbank-Aktion ausgeführt werden.

Hintergrund: Es kann sein, dass die Methode aufgerufen wird, wenn eine Component im Rahmen eines Collection-Loads instanziiert wird. In diesem Fall ist bereits ein Datareader auf der Datenbank geöffnet. Eine Datenbank-Aktion würde zu einer Exception führen.

OnAfterLoad( )

Verfügbar für Component

protected virtual void OnAfterLoad( )

Diese Methode kann in der Component überschrieben werden.

Sie wird aufgerufen, nachdem der Inhalt der Component aus der Datenbank gelesen wurde.

GetTableName( )

Verfügbar für Component

public virtual string GetTableName(string propName)

Gibt den Tabellennamen eines bestimmten Properties zurück. Falls es das Property nicht gibt bzw. das Property nicht mit einer Datenbankspalte verknüpft ist, wird String.Empty zurückgegeben.

GetDefaultLabel( )

Verfügbar für Component.

public string GetDefaultLabel(string propName)

Gibt das Default-Label eines bestimmten Properties zurück. Falls es das Property nicht gibt, wird String.Empty zurückgegeben.

Das Label wird in der aktuellen Sprache zurückgegeben.

GetPropertyMdt( )

Verfügbar an Component / Collection

public MLContainer GetPropertyMdt(string propertyName)

Ermittelt den Metadatentyp des Properties propertyName. Sie ermöglicht dynamisch den Zugriff auf die mdt_-Properties der Factory-Klasse.

Siehe auch Abschnitt Metadaten von Properties.

Die öffentlichen Properties können mit dem Property  ComponentProperties ermittelt werden.

GetProperty( )

Verfügbar für Component.

public virtual object GetProperty(string propertyName)

Ermittelt den Wert des öffentlichen Properties propertyName.

Die öffentlichen Properties können mit dem Property  ComponentProperties ermittelt werden.

SaveCallEntryPointsAllways( )

public void SaveCallEntryPointsAllways( )

Aufruf der LoadCount( )

Verfügbar an Component / Collection

public int LoadCount(string loadCondition)

Ermittelt die Anzahl der Datensätze für die übergebene Load-Condition. Der Zustand des Objektes bzw. der Collection bleibt dabei unverändert.

Save() Methode, wobei die Entry-Points auch durchlaufen werden, wenn der Status der Komponente Unchanged ist.

MarkForDeletion( )

Verfügbar an Component

public void MarkForDeletion( )

Mit dieser Methode wird dem Property StateBeforeUpdate

Verfügbar für Component.

public FrameworkComponentState StateBeforeUpdate {get, set}

Dieses Property übernimmt den Wert des Properies State direkt bevor im Save der Datenbank-Befehl ausgeführt wird. Dieser Wert bleibt bis zum nächsten Save() erhalten.

Somit steht in den Methoden OnAfterSave() und OnAfterSaveCustom() bzw. nach einem Save-Vorgang der Status der Component weiterhin zur Verfügung. Das Property State hingegen nimmt nach der Datenbank-Aktion den Wert Unchanged an.

In den Methoden OnBeforeSave() und OnBeforeSaveCustom() hat dieses Property keinen klar definierten Wert. IsMarkedForDeletion der Wert true zugewiesen.

An der dazugehörigen Collection können anschließend mit der Methode die markierten Objekte aus der Collection gelöscht werden.

DeleteMarkedObjects( )

Verfügbar in Collection

public void DeleteMarkedObjects( )

Mit dieser Methode wird an allen Objekten der Collection, in denen das Property StateBeforeUpdate

Verfügbar für Component.

public FrameworkComponentState StateBeforeUpdate {get, set}

Dieses Property übernimmt den Wert des Properies State direkt bevor im Save der Datenbank-Befehl ausgeführt wird. Dieser Wert bleibt bis zum nächsten Save() erhalten.

Somit steht in den Methoden OnAfterSave() und OnAfterSaveCustom() bzw. nach einem Save-Vorgang der Status der Component weiterhin zur Verfügung. Das Property State hingegen nimmt nach der Datenbank-Aktion den Wert Unchanged an.

In den Methoden OnBeforeSave() und OnBeforeSaveCustom() hat dieses Property keinen klar definierten Wert. IsMarkedForDeletion den Wert true hat, die Methode Delete() ausgeführt.

Remove( )

Verfügbar in Collection

Diese Methode entfernt Objekte aus der Collection. Der Status des entfernten Objektes wird dabei auf Deleted gesetzt. D.h., ein Save() hätte ggf. einen physischen Delete auf der Datenbank zur Folge.

Diese Methode ist funktional identisch mit der Methode Delete( ).

public void Remove( Object )

Entfernt das übergebene Objekt aus der Collection.

public void Remove( SelectedRowsCollection )

Entfernt alle in der übergebenen SelectedRowsCollection angegebenen Objekte aus der Collection.

Drop( )

Verfügbar in Collection

Diese Methode trennt Objekte aus der Collection heraus. Dabei bleibt der Status der Objekte erhalten.

public void Drop( guid )

Entfernt das mit der übergebenen Guid definierte Objekt aus der Collection.

public void Drop( DevFrameworkObject )

Entfernt das übergebene Objekt aus der Collection.

public void Drop( SelectedRowsCollection )

Entfernt alle Komponenten aus der Collection, deren IDs in der übergebenen SelectedRowsCollection enthalten sind.

Dispose( )

Verfügbar in Collection

Die Collection wird geleert und alle verwendeten Ressourcen freigegeben. Nach dieser Operation kann die Collection nicht mehr verwendet werden.

Add( )

Verfügbar in Collection

Diese Methode fügt ein Objekt in die Collection ein. Es wird die Index-Position des Objektes zurückgegeben.

public int Add( object )

Am eingefügten Objekt wird die Collection-Eigenschaft auf die neue Collection geändert.

public int Add( object, bool setCollection )

Wenn der Parameter setCollection mit false angegeben wird, dann wird die Collection-Eigenschaft des Objektes nicht verändert.

AddRange()

Verfügbar in Collection

Diese Methode fügt mehrere Objekte in die Collection ein. Sie können dieser Methode ganze Collections übergeben. So ist es beispielsweise möglich, zwei Collections zusammenzuführen.

Die Methode hat als Parameter den Typ IEnumerable<DevFrameworkObject>. So können auch generische Listen übergeben werden, die z.B. mit einer Linq-Query ermittelt wurden.

public void AddRange(IEnumerable<DevFrameworkObject> value)

An allen hinzugefügten Elementen wird die die Collection-Eigenschaft auf die neue Collection geändert.

public void AddRange(IEnumerable<DevFrameworkObject> value, Boolean setCollection)

Wenn der Parameter setCollection mit false angegeben wird, dann wird die Collection-Eigenschaft der hinzugefügten Objekte nicht verändert.

Insert( )

Verfügbar an Collection

Fügt ein Objekt an eine bestimmte Position in die Collection ein.

public int Insert( int index, object )

Mit Index 0 wird das Objekt am Anfang der Collection eingefügt. Mit Index größer oder gleich Collection.Count wird das Objekt am Ende der Collection eingefügt.

Am eingefügten Objekt wird die Collection-Eigenschaft auf die neue Collection geändert.

public int Insert( int index, object, bool setCollection )

Wenn der Parameter setCollection mit false angegeben wird, dann wird die Collection-Eigenschaft des Objektes nicht verändert.

MoveItem()

Verfügbar an Collection

int Collection.MoveItem(DevFrameworkObject itemToMove, int indexDelta)

Verschiebt den übergebenen Eintrag und gibt den neuen Index des verschobenen Eintrags zurück. Der Parameter indexDelta gibt an, wie weit der Eintrag verschoben werden soll. Bei negativen Werten wird nach oben und bei positiven Werten nach unten verschoben. Wird ein Wert angegeben, der die Grenzen der Collection sprengt, dann wird der Eintrag maximal an die Grenze der Collection (Anfang oder Ende) verschoben.

Wird ein Eintrag übergeben, der nicht Bestandteil der Collection ist, dann wird eine Exception geworfen.

Beispiel:

// verschiebt den ausgewählten Artikel einen Eintrag nach oben
this.oArticleColl.MoveItem(this.oArticleSelected, -1);

// verschiebt den ausgewählten Artikel 2 Einträge nach unten
this.oArticleColl.MoveItem(this.oArticleSelected, 2);

MoveItemTo()

Verfügbar an Collection

void Collection.MoveItemTo(DevFrameworkObject itemToMove, int targetIndex)

Verschiebt den übergebenen Eintrag an eine bestimmte Stelle. Der Parameter targetIndex gibt den Index an, an den der Eintrag verschoben werden soll.

Wird ein Eintrag übergeben, der nicht Bestandteil der Collection ist, dann wird eine Exception geworfen.

Beispiel:

// verschiebt den ausgewählten Artikel an den Anfang der Collection
this.oArticleColl.MoveItemTo(this.oArticleSelected, 0);

CreateNewRecord( )

Verfügbar an Collection

DevFrameworkObject Collection.CreateNewRecord()

Erzeugt passend zur Collection einen neuen Record. Der Rückgabetyp ist DevFrameworkObject bzw. IDevFrameworkObject. Es muss ggf. ein entsprechender cast eingebaut werden.

Beispiel:

IcdCustomer oCustomerNew = this.oCustomerColl.CreateNewRecord() as IcdCustomer;

NewRecord( )

Verfügbar an Collection

DevFrameworkObject Collection.NewRecord()

Erzeugt passend zur Collection einen neuen Record und fügt ihn am Ende der Collection ein. Der Rückgabetyp ist DevFrameworkObject bzw. IDevFramerworkObject. Es muss ggf. ein entsprechender cast eingebaut werden.

Beispiel:

IcdCustomer oCustomerNew = this.oCustomerColl.NewRecord() as IcdCustomer;

UpdateRelationKey( )

Verfügbar innerhalb von Component und Collection

protected bool UpdateRelationKey(string propertyName, string key)

Diese Funktion speichert an der Instanz der Component bzw. der Collection pro übergebenem Property-Namen einen Schlüssel. Dabei wird geprüft, ob sich der Schlüssel gegenüber dem letzten Aufruf dieser Funktion geändert hat. Bei einer Änderung wird true zurückgegeben. Wenn sich der Schlüssel nicht geändert hat, wird false zurückgegeben.

Diese Funktion kann z.B. dazu verwendet werden, um in Individual Properties bei der Änderung eines Schlüssel-Wertes einen Reload zu veranlassen.

Die Funktion ist protected und kann somit nur innerhalb der Component bzw. der Collection verwendet werden.

Beispiel:

// Get-Methode des Individual Properties "oCustomerIndiv"

if (this.oCustomerMember == null)
{
    this.oCustomerMember = cdCustomerFactory.Create(this.Global);
}

String sWhere = "[lngCustomerID] = " + DB.SqlString(this.lngCustomerID);
if (this.UpdateRelationKey("oCustomerIndiv", sWhere)
{
    // Die Suchbedingung – also der Key – hat sich geändert. ==> Reload
    this. oCustomerMember.Load(sWhere);
}
return this.oCustomerMember;

SetCommandTimeout( )

Verfügbar an Data-Collection

public void SetCommandTimeout(int seconds)

Damit kann vor einem Load der Timeout des SQL-Commands gesetzt werden.

In Framework Studio haben alle Commands per Default einen Timeout von 300 Sekunden. Wenn ein Statement längere Zeit benötigt, dann führt das zu einer Exception. Das kann in seltenen Fällen bei komplexen Statements auf großen Datenbeständen der Fall sein.

Mit dem Wert 0 wird der Timeout komplett deaktiviert. Das bedeutet, dass das Statement im schlimmsten Fall endlos laufen kann.

Beispiel:

// Timeout deaktivieren
this.oCollection.SetCommandTimeout(0);
// Daten lesen.
this.oCollection.Load("<very complex condition>");

Properties in jeder Component / Collection

ComponentProperties

Verfügbar für Component.

public virtual System.Collections.Specialized.StringCollection ComponentProperties {get}

Gibt eine Liste mit den Namen aller Properties zurück.

Es werden nur Properties ausgegeben, die public sind.

Diese Namen kann man mit verschiedenen Methoden verwenden. Z.B:

• GetProperty( )
• GetDefaultLabel( )

State

Verfügbar für Component.

public FrameworkComponentState State {get, set}

Status der Komponente. Dieser kann z.B. im OnBeforeSave() ausgewertet werden.

Mit dem Ausführen der Datenbank-Aktion erhält das Property den Wert Unchanged bzw. UnchangedButDeleted. Im OnAfterSave() bzw. nach dem Save() kann der ursprüngliche Wert über das Property StateBeforeUpdate erfragt werden.

Das Enum FrameworkComponentState hat folgende Werte:

New:

Die Komponente wurde instanziiert und es wurden keine Daten mit Load() eingelesen. Werden Properties in dieser Komponente geändert, bleibt der Status weiterhin New. Ein Save() führt einen Insert-Befehl auf der Datenbank aus.

Unchanged:

Die Komponente wurde mit Load() eingelesen und die Daten wurden danach nicht verändert. Ein Save() führt keine Aktion auf der Datenbank aus.

Changed:

Die Komponente wurde mit Load() eingelesen und der Wert mindestens eines Properties wurde geändert. Ein Save() führt einen Update-Befehl auf der Datenbank aus.

Soll ein Insert-Befehl erzwungen werden, muss der Status manuell auf New gesetzt werden.

Deleted:

Die Komponente wurde mit Load() eingelesen und es wurde die Methode Delete() aufgerufen. Ein Save() führt einen Delete-Befehl auf der Datenbank aus.

NewButDeleted:

Die Komponente wurde mit einem new() erstellt und es wurde die Methode Delete() aufgerufen. Ein Save() führt keine Aktion auf der Datenbank aus.

UnchangedButDeleted:

Nachdem die Methode Delete() aufgerufen und mit Save() der Delete-Befehl auf der Datenbank ausgeführt wurde, erhält die Komponente diesen Status. Ein weiterer Save() führt keine Aktion auf der Datenbank aus.

Wird der Wert eines Properties geändert, behält die Component diesen Status – er wird nicht auf Changed gesetzt.

StateBeforeUpdate

Verfügbar für Component.

public FrameworkComponentState StateBeforeUpdate {get, set}

Dieses Property übernimmt den Wert des Properies  State direkt bevor im Save der Datenbank-Befehl ausgeführt wird. Dieser Wert bleibt bis zum nächsten Save() erhalten.

Somit steht in den Methoden OnAfterSave() und OnAfterSaveCustom() bzw. nach einem Save-Vorgang der Status der Component weiterhin zur Verfügung. Das Property State hingegen nimmt nach der Datenbank-Aktion den Wert Unchanged an.

In den Methoden OnBeforeSave() und OnBeforeSaveCustom() hat dieses Property keinen klar definierten Wert.

IsMarkedForDeletion

Verfügbar für Component.

public bool IsMarkedForDeletion {get, set}

Über dieses Property ist es möglich, ein mehrstufiges Löschen zu realisieren. Das ist notwendig, wenn z.B. die Datensätze in einem Grid zum Löschen markiert werden sollen, bevor sie gelöscht werden. Wenn Sie die Methode Delete( ) verwenden, werden die entsprechende Zeilen im Grid nicht mehr angezeigt. Dieses Property ist vor allem dann interessant, wenn die Component in einer Collection verarbeitet wird.

Wenn an mindestens einem Element in einer Collection diese Eigenschaft true ist, dann liefert Collection.IsModified den Wert true.

Ist IsMarkedForDeletion true, dann wird im Grid in der entsprechenden Zeile das im Grid-Property RowDeletedIcon hinterlegte Icon angezeigt. (siehe Grid Properties)

Mit der Methode DeleteMarkedObjects an der entsprechenden Collection wird an jedem Objekt, an dem das Property den Wert true hat, ein Delete aufgerufen.

IsModified

Verfügbar für Component und Collection.

Component:

public bool IsModified {get}

IsModified ist true, wenn State nicht den Wert Unchanged hat. Insbesondere gilt somit für neue Components (State=New) IsModified = true.

Collection:

public bool IsModified {get}

IsModified ist true, wenn bei mindestens einem Element der Liste die Eigenschaft IsModified den Wert true hat oder mindestens ein Element gelöscht oder zum Löschen markiert (IsMarkedForDeletion) wurde.

LoadSize

Verfügbar für Collection mit Datenbank-Bezug

Über dieses Property kann zur Laufzeit festgelegt werden, für wie viele Datensätze beim ersten Laden die Komponenten direkt instanziiert werden sollen. Für alle weiteren Datensätze wird zunächst nur der Primärschlüssel verwaltet. Durch den automatischen Nachlademechanismus werden die Komponenten dann beim ersten Zugriff automatisch nachgeladen und instanziiert.

Wenn dieses Property auf einen Wert kleiner oder gleich Null gesetzt wird, werden direkt alle Komponenten instanziiert. Ein Nachladen ist dann nicht mehr nötig. Dies ist vor Allem dann sinnvoll, wenn anschließend ohnehin auf alle Components der Collection zugegriffen wird, beispielsweise durch eine foreach Schleife.

LoadMaxCount

Verfügbar für Collection mit Datenbank-Bezug.

Dieses Property gibt an, wie viele Datensätze maximal eingelesen werden sollen.

Es muss gesetzt werden, bevor der Load ausgeführt wird.

Der Standardwert ist 0. Das bedeutet keine Begrenzung.

// Beispiel: nur die ersten 30 Sätze lesen:

this.oContactHistoryColl = new cdContactHistoryColl(this.Global);
this.oContactHistoryColl.LoadMaxCount = 30;
this.oContactHistoryColl.Load( this.sWhereClause );

Das bringt bei sehr großen Datenmengen einen Geschwindigkeits-Vorteil.

Dieses Property hat keinen Einfluss auf das an die Datenbank geschickte Statement. Die Datenbank liefert bei dem ausgeführten Select alle Datensätze.

Die Collection bricht bei Erreichen der Grenze die Verarbeitung ab. Dadurch müssen die überflüssigen Primary-Key-Informationen nicht eingelesen werden. Bei sehr vielen Treffern entlastet das auch den Hauptspeicher erheblich.

Noch besser ist es, wenn es möglich ist, die Suchbedingung so zu formulieren, dass die Datenbank-Abfrage nicht zu viele Treffer liefert. Dadurch ist der Performance-Gewinn deutlich größer durch setzen dieses Properties.

Besonders groß ist der Effekt, wenn die Datenbank-Abfrage eine Sortierung beinhaltet. Denn trotz dem Setzen dieses Properties muss die Datenbank alle Treffer sortieren.

Metadaten von Properties

Zur Laufzeit kann der Entwickler auf die Metadatentyp-Informationen der Properties zugreifen. Dafür stehen folgende Möglichkeiten zur Verfügung:

1. Über die Factory-Klasse
2. Mit der Methode GetPropertyMdt

Die Factory-Klasse, welche mit den Interfaces kompiliert werden, bietet für jedes Component-Property eine Eigenschaft mdt_... an, welche eine Instanz mit den Metadatentyp-Informationen zurückgibt.

Beispiel: An der Component cdArticle gibt es ein Property sArticleID.

int intMaxSize = cdArticleFactory.mdt_sArticleID.Size;

Mit der Methode GetPropertyMdt() kann mithilfe des Property-Namen die Metadatentyp-Information ermittelt werden. Das ermöglicht auch die Arbeit auf der Ebene DevFrameworkObject.

Beispiel

MLContainer mdt = oArticle.GetPropertyMdt("sArticleID");
if (mdt is MDTStringBase)
{
    int intSize = ((MDTStringBase)mdt).Size;
}

Folgende Basis-Klassen liegen den Metadatetypen zugrunde:

Klasse-Hierarchie	Verwendung (Properties)
MLContainer	Allgemeine Basis. Sie wird für Properties verwendet, die keinen Metadatentyp besitzen: DefaultLabel / MLColumnCaption / MLToolTip/ DragSource
MetadatatypeBase	Basis für alle Metadatentypen: FormatPattern / FormatMask
MDTStringBase	Basis für Strings (FSstring): Size/ Values
MDTBoolBase	Basis für Booleans (FSbool): Values
MDTByteArrayBase	Basis für Byte-Arrays (FSByteArray): Values
MDTDateTimeBase	Basis für DateTime (FSDateTime): Values
MetadatatypeNumberBase	Allgemeine Basis für Numerische Metadatentypen: Precision/ Scale
MDTByteBase	Basis für Byte (FSbyte): Values
MDTDecimalBase	Basis für Decimal (FSdecimal): Values
MDTDoubleBase	Basis für Double (FSdouble): Values
MDTFloatBase	Basis für Float (FSfloat): Values
MDTIntBase	Basis für Int (FSint): Values
MDTLongBase	Basis für Long (FSlong): Values
MDTShortBase	Basis für Short (FSshort): Values

Beschreibungen der o.g. Properties

DevMLString DefaultLabel: Das mehrsprachige Default-Label

DevMLString MLColumnCaption: Die mehrsprachige Spalten-Beschriftung. Wenn diese nicht gepflegt ist, wird DefaultLabel zurückgegeben.

DevMLString MLToolTip: Der mehrsprachige Tooltip.

int Precision: Anzahl von Nachkommastellen; wird nur bei numerischen Typen angeboten.

int Scale: Maximale Anzahl von Stellen inkl. Nachkommastellen. Wird nur bei numerischen Typen angeboten.

int Size: Maximale Länge eines Strings.

FrameworkFormatMask FormatMask: Gibt einen Wert mit dem Typ FrameworkFormatMask zurück. Dieses Enum kann folgende Werte beinhalten:

• FrameworkFormatMask.None
• FrameworkFormatMask.LowerCase
• FrameworkFormatMask.UpperCase
• FrameworkFormatMask.DateOnlyShort
• FrameworkFormatMask.DateOnlyMedium
• FrameworkFormatMask.DateOnlyLong
• FrameworkFormatMask.DateTimeShort
• FrameworkFormatMask.DateTimeMedium
• FrameworkFormatMask.DateTimeLong
• FrameworkFormatMask.TimeOnlyShort
• FrameworkFormatMask.TimeOnlyMedium
• FrameworkFormatMask.TimeOnlyLong
• FrameworkFormatMask.Decimal
• FrameworkFormatMask.Integer
• FrameworkFormatMask.PositiveInteger
• FrameworkFormatMask.NegativeInteger
• FrameworkFormatMask.UserDefined

string FormatPattern: Ein individuelles Format-Pattern. Dieses kann z.B. bei numerischen Typen für die Formatierung von Zahlen in Strings verwendet werden. Bei FSstrings handelt es sich um einen regulären Ausdruck.

[,] Values: Dieser Array beinhaltet die im Metadatentyp vorgenommenen Value-Einschränkungen. Die erste Dimension des Arrays bildet die einzelnen Einschränkungen ab. In der 2. Dimension sind der Von- und der Bis-Wert enthalten. Wenn nur der Von-Wert definiert wurde, dann steht dieser auch im Bis-Wert.

Beispiel: A, B, E-G bildet folgendes Array

new string[,] {
    {@"A", @"A"},
    {@"C", @"C"},
    {@"E", @"G"} };

Kopieren / Mergen kompletter Components

Es ist möglich, komplette Components zu kopieren oder auch zusammenzuführen. Das funktioniert auch, wenn es sich bei Quelle und Ziel um unterschiedliche Repositories handelt.

Zu beachten ist, dass der Dialog sehr viele Freiheiten bietet. Dies ermöglicht natürlich auch fehlerhafte Stände zu erstellen. Dieser Mechanismus ist für versierte Benutzer konzipiert. Grundsätzlich sollte der Benutzer wissen, was er tut und VOR der Aktion sicherstellen, dass alle von der Component benötigten Elemente am Ziel vorhanden sind.

Aktionen

• Eine Component kann über das Kontext Menü an der Component kopiert werden.

• Eine Component kann über das Kontext Menü am Namespace eingefügt werden.

• Eine Component kann über das Kontext Menü an der Component gemerged (zusammengeführt) werden.

Einfügen

Wird eine Component ohne Basis kopiert, kann diese überall eingefügt werden. Eine Customization wiederrum kann nur erstellt werden, wenn im Package noch keine Customization vorhanden ist und die passende Basis existiert.

Dialog

Registerkarte Summary

Die Summary zeigt, ob beim Paste oder Merge Konflikte gefunden wurden.

MergeDialog - Summary

Framework Studio versucht bei der Aktion die benötigten Elemente im Ziel-Package auf zwei verschiedenen Wegen zu finden:

1. Über die interne ID: Das funktioniert meist dann, wenn Quell- und Ziel-Package identisch sind oder wenn Elemente aus einem gemeinsamen Basis-Package verwendet werden.

2. Über den Namen: Wenn über die ID nichts gefunden wird, wird nach einem gleichnamigen Element (z.B. Metadatentyp, Component, Property) gesucht. Das ist vor allem dann sehr nützlich, wenn nach und nach mehrere Components in ein anderes Package kopiert werden.

3. Wenn diese Wege nicht zum Ziel führen, wird dies als Konflikt betrachtet und der Benutzer muss nach einer Lösung suchen. Teilweise kann das auf den folgenden Registerkarten erfolgen. Manchmal ist es aber auch nötig, die Aktion abzubrechen, erst die Voraussetzungen zu schaffen (z.B. eine DBTable anlegen) und die Aktion anschließend noch einmal auszuführen.

Die anderen Registerkarte sollten also der Reihe nach – wie ein Wizard – durchgearbeitet und die entsprechenden Einstellungen vorgenommen werden, um die Aktion am Ende korrekt ausführen zu können. Die Registerkarte sind bei beiden Aktionen Paste und Merge identisch.

Registerkarte Needed Types

Bei den Needed Types werden alle Typen aufgelistet, die nicht zum Standard gehören. Diese können beliebig ausgetauscht werden. Das kann z.B. dann sinnvoll sein, wenn eine benötigte Component vorher auch schon kopiert wurde und jetzt ggf. unter einem anderen Namen in einem anderen Namespace zu finden ist.

Registerkarte General

Unter General können die Interfaces, die Description und die ControlTypes überschrieben werden.

Registerkarte Join Tables

Bei einer JoinTable stehen zwei Aktionen zur Verfügung, wenn dies nicht durch die Checkbox ignoriert wird. Ein Insert fügt eine neue JoinTable an während der Replace die Werte an der JoinTable ersetzt.

Registerkarte Virtual Columns

Auch bei den VirtualColumns gibt es die Aktionen Replace, Insert oder Ignore. Diese verhalten sich wie bei der JoinTable.

Registerkarte Properties

Ein Property bietet beim Einfügen noch die weitere Möglichkeit, den Namen anzupassen. Der Replace ersetzt alle Werte für das ausgewählte Property.

Registerkarte Methods

Bei den Methoden ist wie bei den Properties eine Umbenennung möglich.

Merge

Mit einem Merge kann erreicht werden, dass Änderungen an einer Component in einer Kopie davon nachgezogen werden. Was nicht möglich ist, sind gelöschte Elemente durch den Merge zu entfernen. Es werden nur neu hinzugekommene oder geänderte beachtet.

Für jedes Element wird in der Component das zugehörige Element gesucht und dann ein Replace vorgeschlagen. Ein Replace ändert nur dann die Daten, wenn diese sich in der kopierten Component auch geändert haben. Es kann also eine Component mit sich selbst gemerged werden und diese ist danach nicht modified, da es keine Änderungen gab.