1.4.1.1. Attachment Handling und API

• Inline-Attachments gehören jetzt immer zu genau einem HTML-Feld in der Datentabelle.
  Dessen Feldname steht jetzt analog zu normalen Attachments in der Spalte OrmAttachment.Category.
• Die ContentID eines Inline-Attachments ist kein starker Schlüssel.
  Diese kann aus Fremdsystemen kommen und durch Copy&Paste in verschiedenen Datensätzen und/oder verschiedenen HTML-Feldern gleich sein. Zwar sollten gemäß RFC2392 Content-IDs weltweit eindeutig sein und daher immer auf denselben Content verweisen, das gilt aber nicht für die Leserechte des Datensatzes in BA, wenn z.B. eine Termineinladung in Kalender mehrerer Benutzer repliziert wird.
• Für den Zugriff auf Inline-Attachments muss jetzt immer OrmAttachments.Oid verwendet werden. Diese steht jetzt auch im HTML in der Datenbank. Syntax: img src="cid:AttachmentOID"
• Die Eigenschaft OrmAttachment.IsInline existiert nicht mehr.
  Da jedes Attachment notwendigerweise zu genau einem Feld = einer Kategorie gehört und diese auch für den Zugriff erforderlich ist, ist die Eigenschaft IsInline immer inhärent eindeutig. Immer wenn die Kategorie ein HTML-Feld ist, ist es notwendigerweise ein Inline-Attachment und vice versa.
• Die Zuweisung von HTML mit Inline-Images zu anderen Datensätzen und/oder Datenspalten ist jetzt direkt möglich. Die darin referenzierten Inline-Attachments werden beim Speichern des Zieldatensatzes automatisch mit übernommen und die AttachmentOIDs umgeschlüsselt.
• Die Attachment-Funktionen auf Datensatzebene interagieren nicht mehr mit dem ORM-Cache. Es obliegt dem Aufrufer ggf. LoadFromCache / SaveToCache aufzurufen.

Constants.Attachments… [bei Compilerfehler]

Die Konstanten existieren nicht mehr, da es sich jetzt um Feldnamen von Datensätzen handelt.

• DefaultAttachmentsCategory => nameof(OrmBABase.DefaultAttachments)
• InlineImagesCategory
  Hier muss jetzt immer der Name des HTML-Feldes angegeben werden, zu dem das Inline-Image gehört.

GetAttachmentById, GetAttachments, AddAttachment, RemoveAttachment: kein ORM Cache

Die Methoden auf Datensatzebene haben früher standardmäßig die Daten des aktuellen Datensatzes mit den Werten aus dem ORM-Cache überschrieben und die Änderungen danach in selbigen zurückgeschrieben, falls RecordCacheId gefüllt war und nicht explizit reloadOrmFromCache: false übergeben wurde. Das ist jetzt nicht mehr der Fall und der Parameter reloadOrmFromCache existiert nicht mehr.

Wenn Code darauf angewiesen ist, dass eventuelle, ungespeicherte Maskendaten im ORM Cache gelesen oder geschrieben werden sollen, muss das explizit erfolgen (wie bei allen anderen Datensatz-API-Funktionen auch).

Die datensatzunabhängigen Funktionen in Api.Attachments können wie bisher den ORM-Cache benutzen.

GetAttachments Übergabeparameter [bei Compilerfehler]

Beispiel:

bc… // alt
ormBABase.GetAttachments(new string[] { Name }, AttachmentInlineType.Both)

// neu
ormBABase.GetAttachments(Name)

AttachmentInlineType inline

Eine Filterung nach IsInline ist mangels dieser Eigenschaft nicht mehr möglich und nicht mehr notwendig. Der entsprechende Übergabeparameter existiert nicht mehr und muss ggf. entfernt werden.

categories -> category

Die Methoden zum Abrufen von Attachments OrmBABase.GetAttachments und Api.Attachment.GetAttachments akzeptieren jetzt nur noch eine Kategorie pro Aufruf, da alles andere logisch nicht sinnvoll ist. Die Aufrufe sind entsprechend umzustellen.

Falls doch mehrere Kategorien auf einmal abgerufen werden sollen (aber nicht alle), sollte direkt eine Abfrage auf OrmAttachment verwendet werden.

GetAttachmentByContentID [bei Compilerfehler]

Die Methode existiert nicht mehr, da das Ergebnis nicht eindeutig ist, wenn dasselbe Inline-Attachment beispielsweise für mehrere Terminteilnehmer repliziert ist. Es sollte statt dessen GetAttachmentById verwendet werden. Die dafür erforderliche OID steht bei HTML-Spalten auch in der Datenbank.

In Api.Html… gibt es Hilfsmethoden, um an die Attachment-OIDs zu kommen bzw. sie umzuschlüsseln.

Api.Attachments.GetAttachmentById [bei Compilerfehler]

Die Methode hat zusätzliche optionale Parameter zum filtern. Falls eine explizite Session übergeben wurde sollte das jetzt per benanntem Parameter geschehen: GetAttachmentById(..., session: mySession);

Api.Attachments.CreateAttachment [bei Compilerfehler]

Die Parameter Kategorie (= Feldname) und Session sind jetzt Pflicht.

category: Falls die Standard-Kategorie gemeint ist, muss nameof(OrmBABase.DefaultAttachments) übergeben werden.

Bei Inline-Images muss der Feldname, zu dem das Attachment gehören soll, übergeben werden. Andernfalls funktioniert das Inline-Attachment nicht.

session: Es muss immer die Session des Objektes angegeben werden, zu dem das Attachment hinzugefügt werden soll. Alles andere gab schon immer eine Exception.

=> Alternativ kann und sollte wo möglich die neue, leistungsfähigere Methode orm.GetOrAddAttachment verwendet werden, die das Erstellen und Hinzufügen eines Attachments bündelt und auch einige Sonderfälle wie z.B. doppelte ContentIDs oder Attachments von Konfigurationen behandelt.

Api.Attachments.AddAttachmentToOrm [bei Compilerfehler]

Der optionale Parameter Session existiert nicht mehr. Es wird nun automatisch die Session des übergebenen OrmAttachment-Objekts verwendet. Jede andere hat schon immer eine Exception gegeben.

ControlHelperController.AttachmentDownloadByContentId

Eine Funktion zum Abrufen eines Attachments anhand seiner Content-ID ist nicht mehr möglich, da diese nicht eindeutig ist und dadurch unter anderem falsche Leserechte greifen könnten.

Statt dessen sollte DownloadAttachment verwendet werden, was als Parameter die OID des OrmAttachment benötigt. Diese steht bei HTML-Spalten jetzt auch als "cid:OID"-URL in der Datenbank.

Api.Html.ConvertInlineAttachmentsToDownloadUrl kann die URLs in Inline-Images automatisch anpassen.

GetTotalFileSizeOfAttachmentControl [bei Compilerfehler]

Die Methode existiert nicht mehr, weil die Performance schlecht war. Es sollte Api.Attachments.GetReadableSize(size) verwendet werden. Die Größe bekommt man (wie bisher) über Api.Attachments.GetTotalFileSize

GetFileSizeInBytes [bei Compilerfehler]

Die Methode heißt jetzt Api.Attachments.GetTotalFileSize.

Export von HTML mit Inline-Images

Falls Projekt-Code HTML mit Inline-Images exportiert bzw. an Fremdsysteme weiter reicht, sollten die darin enthaltenen URLs der Inline-Images von OID auf Content-ID umgeschrieben werden. Das geht mit der Funktion Api.Html.ConvertHtmlInlineToContentId. Diese liefert auch gleich die Liste der benötigten Attachments.