Gedys CXM: Leitfaden für Anpassungen

1.4.1.2. Umstellung RelationCategory auf GUID

Der Datentyp für Relationskategorien hat sich aus Performancegründen auf GUID geändert.

  • Es werden wie gehabt die GUIDs der Enum-Werte für die Relationskategorie verwendet.
  • Die Relationskategorie “keine” entspricht jetzt Guid.Empty.
  • Die Relationskategorie null bedeutet “alle” Kategorien eines Relationstyps. Das ist nur bei Selektionen erlaubt nicht beim Schreiben von Relationen.

Die meisten API-Methoden mit Relationskategorie als String stehen weiterhin als obsolet zur Verfügung. Details siehe unten. Es wird empfohlen immer auf die aktuellen APIs umzustellen, aber das muss nicht sofort geschehen.

Wo die Umwandlung von Relationskategorie-Strings in GUIDs notwendig oder gewünscht ist, sollte wie folgt vorgegangen werden:

  • Optionale Relationskategorie-Strings sollten mit .ToGuidOrNull() umgewandelt werden.
  • Nicht optionale Relationskategorie-Strings, beispielsweise zum erstellen von Relationen, sollten mit .ToGuid() umgewandelt werden.
  • Wenn eine Relationsdefinition für den Schreibzugriff verwendet werden soll, sollte deren optionale Relationskategorie mit .GetValueOrDefault() umgewandelt werden. Das ist auch beim zugehörigen Lesezugriff zum Befüllen der aktuell ausgewählten Datensätze des Steuerelements notwendig. Die Vorgehensweise stellt die Kompatibilität mit bestehendem Code sicher, da bei Relationsdefinitionen nicht zwischen “leere Kategorie” und “alle Kategorien” unterschieden werden kann.
  • Wenn eine Relationskategorie in einen String für die UI umgewandelt werden muss, sollte .ToUpperString() bzw. ?.ToUpperString() verwendet werden.

Umstellung der Model-Klassen [bei Compilerfehler]

  • RelationTypeModel und RelatedDataModel: RelationCategory ist jetzt Typ Guid. Die Option “alle” ist hier nicht erlaubt.
  • RelationDefinitionModel: RelationCategory ist jetzt Typ Guid?. null entspricht “alle” Kategorien.
    Wenn eine Relationsdefinition mit Kategorie null für ein Maskensteuerelement oder andere Schreibzugriffe verwendet wird, wird immer die Kategorie “leer” = Guid.Empty verwendet. Bei eigenen Maskensteuerelementen ist entsprechend RelationCategory.GetValueOrDefault() in den Renderern für die Datenbindung sowohl lesend als auch schreibend zu nutzen.

Umstellung der DataProvider Properties [bei Compilerfehler]

  • CDPOrmDataProperties: FilterRelationCategory ist jetzt Typ Guid?. null entspricht “alle” Kategorien.
  • GridDataProviderParameter.RestrictToRelationParameter: RelationCategory ist jetzt Typ Guid?. null entspricht “alle” Kategorien.

RelationDefinitionTargetAttribute, RelationDefinitionTargetInjectAttribute

RelationCategory ist jetzt Typ Guid?.

Sonderfall
Wenn eine Relationsdefinition sich explizit nur auf die Kategorie “leer” beziehen soll (Beispiel RelatedMainParents), sollte zukünftig der String “00000000-0000-0000-0000-000000000000” als Kategorie verwendet werden und nicht mehr null (= “alle”).

API Funktionen in OrmBABase [bei Compilerfehler]

Alle API-Funktionen sind auf Guid bzw. Guid? umgestellt. Zusätzlich nutzen jetzt alle Relationsfunktionen EnumRelationType.

Die alten Funktionen werden als obsolete Extension-Methoden weiterhin angeboten. Das ist bei Zugriffen auf konkrete Datensätze code-kompatibel, Beispiel: orm.AddSource(...).
Bei Methoden des Datensatzes selbst funktioniert der Aufruf der Extensions nur, wenn “this.” vorangestellt wird. Es wird empfohlen wenn möglich gleich auf die neue API umzustellen.

Beispiel:

// alt
public OrmEvent RelatedEvent =>
    GetSourcePrimary<OrmEvent>(EnumRelationType.Parent, EnumParentRelationSubTypesExtension.EventCategoryGuid);

// oder
public OrmEvent RelatedEvent =>
    GetSourcePrimary<OrmEvent>(EnumRelationType.Parent.ValueGuid, EnumParentRelationSubTypesExtension.EventCategory.GuidString);

// neu
public OrmEvent RelatedEvent =>
    GetSourcePrimary<OrmEvent>(EnumRelationType.Parent, EnumParentRelationSubTypesExtension.EventCategory);

Api.Relation… [bei Compilerfehler]

Alle API-Funktionen sind auf Guid bzw. Guid? umgestellt. Die alten Funktionen werden als obsolete Extension-Methoden weiterhin angeboten und sind code-kompatibel.

CriteriaOperatorBuilder [bei Compilerfehler]

Die Funktionen mit Relationskategorie sind auf Typ Guid? umgestellt. Eine Kompatibilitätsschicht ist hier nicht sinnvoll möglich. Alle Aufrufe müssen angepasst werden.

Programmierte Criteria-Formeln

Konfigurierte Formeln werden i.d.R. automatisch angepasst, aber bei programmierten Formeln ist das nicht möglich. Das bedeutet man muss sicherstellen, das bei programmierten Formeln der Datentyp korrekt ist:

[RelationCategory] = 'guid' => [RelationCategory] = { guid }

[RelationCategory] in ('guid1', 'guid2'...) => [RelationCategory] in ({ guid1 }, { guid2 }...)

[RelationCategory] is null sowie IsNull([RelationCategory]) => [RelationCategory] = { 00000000-0000-0000-0000-000000000000 }