Teilen über

Dateidaten mit Anlagen- und Notizdatensätzen verwenden

  • Artikel

Anlagentabellen (ActivityMimeAttachment) und Notiztabellen (Anmerkungen) enthalten spezielle Zeichenfolgenspalten, in denen Dateidaten gespeichert werden. Diese Tabellen gab es schon vor den Datei- oder Bildspalten, daher funktionieren sie anders als diese Tabellen.

  • Die binären Dateidaten werden als Base64-kodierte Zeichenfolgen in Zeichenfolgen-Spalten gespeichert. Anhänge werden in der Spalte ActivityMimeAttachment.Body und Notizen in der Spalte Annotation.DocumentBody gespeichert.
  • Dateinamendaten werden in der Spalte FileName gespeichert.
  • Die Daten des MIME-Typs werden in der Spalte MimeType gespeichert.

Da FileName, MimeType, ActivityMimeAttachment.Body und Annotation.DocumentBody Teil der Daten für den Anhang oder den Notiz-Datensatz sind, sollten Sie diese drei Spalten zusammen mit allen anderen Werten aktualisieren.

Sie können die Werte der Spalten activitymimeattachment.body und annotation.documentbody direkt als Base64-kodierte Zeichenfolgen abrufen und festlegen. Die Einstellung dieser Werte sollte in Ordnung sein, solange die Dateien nicht zu groß sind, z.B. unter 4 MB. Standardmäßig beträgt die maximale Größe 5 MB. Sie können diese Spalten so konfigurieren, dass sie Dateien bis zu einer Größe von 128 MB akzeptieren. Wenn Sie die maximale Dateigröße erhöht haben und mit größeren Dateien arbeiten, sollten Sie die bereitgestellten Meldungen verwenden, um die Dateien beim Hoch- oder Herunterladen in kleinere Teile aufzuteilen. Informationen zum Abrufen oder Ändern der Begrenzungen der Dateigröße finden Sie unter Begrenzungen der Dateigröße.

Anhänge

Ein Anhang ist eine Datei, die mit einer E-Mail-Aktivität verbunden ist, entweder direkt oder über eine E-Mail-Vorlage (Vorlage). Der Aktivität oder Vorlage können mehrere Anhänge zugeordnet werden. Sie können Anhangsdateien wiederverwenden, indem Sie den Wert activitymimeattachment.attachmentid so einstellen, dass er auf einen anderen vorhandenen Anhang verweist, anstatt die Eigenschaften body, filename und mimetype zu setzen.

Andere Dataverse Tabellen namens Anhang

Anhang (ActivityMimeAttachment) ist nicht zu verwechseln mit Activityfileattachment, das Dateien unterstützt, die mit der Tabelle Post verbunden sind.

Innerhalb des Schemas Dataverse gibt es auch eine öffentliche Tabelle mit dem Namen Attachment, die in der Web-API als Anhang EntityType angezeigt wird. Diese Tabelle kann abgefragt werden und gibt Daten in der ActivityMimeAttachment-Tabelle wieder. Sie unterstützt jedoch keine Erstellen-, Abrufen-, Aktualisieren- oder Löschenvorgänge. Diese Tabelle wird nicht im Power Apps Designer angezeigt.

Hochladen von Anhangsdateien

Verwenden Sie die InitializeAttachmentBlocksUpload-, UploadBlock- und CommitAttachmentBlocksUpload-Meldungen, um große Dateien für Anlagen hochzuladen.

Wichtig

Sie können diese Nachrichten nur verwenden, um einen neuen Anhang zu erstellen. Wenn Sie versuchen, damit einen bestehenden Anhang zu aktualisieren, erhalten Sie eine Fehlermeldung, dass der Datensatz bereits existiert.

Die folgende statische UploadAttachment-Methode zeigt, wie Sie einen Anhang mit einer Datei unter Verwendung der Klassen InitializeAttachmentBlocksUploadRequest, UploadBlockRequest und CommitAttachmentBlocksUploadRequest erstellen, um eine CommitAttachmentBlocksUploadResponse mit den Eigenschaften ActivityMimeAttachmentId und FileSizeInBytes zurückzugeben.

static CommitAttachmentBlocksUploadResponse UploadAttachment(
   IOrganizationService service,
   Entity attachment,
   FileInfo fileInfo,
   string fileMimeType = null)
{
   if (attachment.LogicalName != "activitymimeattachment")
   {
         throw new ArgumentException(
            "The attachment parameter must be an activitymimeattachment entity.",
            nameof(attachment));
   }

   // body value in activitymimeattachment not needed. Remove if found.
   if (attachment.Contains("body"))
   {
         attachment.Attributes.Remove("body");
   }

   // Try to get the mimetype if not provided.
   if (string.IsNullOrEmpty(fileMimeType))
   {
         var provider = new FileExtensionContentTypeProvider();

         if (!provider.TryGetContentType(fileInfo.Name, out fileMimeType))
         {
            fileMimeType = "application/octet-stream";
         }
   }
   // Don't overwrite mimetype value if it exists
   if (!attachment.Contains("mimetype"))
   {
         attachment["mimetype"] = fileMimeType;
   }

   // Initialize the upload
   InitializeAttachmentBlocksUploadRequest initializeRequest = new()
   {
         Target = attachment
   };

   var initializeResponse =
         (InitializeAttachmentBlocksUploadResponse)service.Execute(initializeRequest);

   string fileContinuationToken = initializeResponse.FileContinuationToken;

   // Capture blockids while uploading
   List<string> blockIds = new();

   using Stream uploadFileStream = fileInfo.OpenRead();

   int blockSize = 4 * 1024 * 1024; // 4 MB

   byte[] buffer = new byte[blockSize];
   int bytesRead = 0;

   long fileSize = fileInfo.Length;

   // The number of iterations that will be required:
   // int blocksCount = (int)Math.Ceiling(fileSize / (float)blockSize);
   int blockNumber = 0;

   // While there is unread data from the file
   while ((bytesRead = uploadFileStream.Read(buffer, 0, buffer.Length)) > 0)
   {
         // The file or final block may be smaller than 4MB
         if (bytesRead < buffer.Length)
         {
            Array.Resize(ref buffer, bytesRead);
         }

         blockNumber++;

         string blockId = Convert.ToBase64String(Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

         blockIds.Add(blockId);

         // Prepare the request
         UploadBlockRequest uploadBlockRequest = new()
         {
            BlockData = buffer,
            BlockId = blockId,
            FileContinuationToken = fileContinuationToken,
         };

         // Send the request
         service.Execute(uploadBlockRequest);
   }

   // Commit the upload
   CommitAttachmentBlocksUploadRequest commitRequest = new()
   {
         BlockList = blockIds.ToArray(),
         FileContinuationToken = fileContinuationToken,
         Target = attachment
   };
   
      return  (CommitAttachmentBlocksUploadResponse)service.Execute(commitRequest);

}

Weitere Informationen:

Hinweis

Diese Beispielmethode enthält eine Logik, mit der versucht wird, den MIME Typ der Datei mit Hilfe der Methode FileExtensionContentTypeProvider.TryGetContentType(String, String) zu ermitteln, wenn er nicht bereitgestellt wird. Wenn der Typ nicht gefunden wird, wird er auf application/octet-stream gesetzt.

Download von Anhangsdateien

Sie können eine Datei mit Anhängen in einem einzigen Vorgang über die Web-API oder in Stücken über das SDK oder die Web-API herunterladen.

Herunterladen von Anhangsdateien in einem einzigen Vorgang über die Web-API

Mithilfe der Web-API können Sie eine Anhangsdatei in einem einzigen Vorgang herunterladen.

Anders als beim Abrufen von Dateispalten liefert diese Methode keine Informationen über die Dateigröße, den Dateinamen oder den MIME Typ.

Anforderung:

GET [Organization Uri]/api/data/v9.2/activitymimeattachments(<activitymimeattachmentid>)/body/$value HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: text/plain

<Base64 string content removed for brevity>

Weitere Informationen:

Download von Anhangsdateien in Chunks

Um die Datei in Stücken abzurufen, verwenden Sie die folgenden Nachrichten entweder mit dem SDK oder der Web-API:

Nachricht Beschreibung
InitializeAttachmentBlocksDownload Gibt den Datensatz der Notiz an, von dem Sie eine Datei herunterladen möchten. Sie gibt die Dateigröße in Bytes und ein file continuation token zurück, mit dem Sie die Datei blockweise über die DownloadBlock-Nachricht herunterladen können.
DownloadBlock Fordert die Größe des Blocks, den Offset-Wert und das Dateifortsetzungs-Token an.

Nachdem Sie alle Blöcke heruntergeladen haben, fügen Sie sie zusammen, um die gesamte heruntergeladene Datei zu erstellen.

Die folgende statische DownloadAttachment-Methode zeigt, wie Sie eine Anlage mithilfe des SDK mit den Klassen InitializeAttachmentBlocksDownloadRequest und DownloadBlockRequest herunterladen. Diese Funktion gibt die byte[]-Daten und den Namen der Datei zurück.

static (byte[] bytes, string fileName) DownloadAttachment(
   IOrganizationService service,
   EntityReference target)
{
   if (target.LogicalName != "activitymimeattachment")
   {
         throw new ArgumentException(
            "The target parameter must refer to an activitymimeattachment record.",
            nameof(target));
   }

   InitializeAttachmentBlocksDownloadRequest initializeRequest = new()
   {
         Target = target
   };

   var response =
         (InitializeAttachmentBlocksDownloadResponse)service.Execute(initializeRequest);

   string fileContinuationToken = response.FileContinuationToken;
   int fileSizeInBytes = response.FileSizeInBytes;
   string fileName = response.FileName;

   List<byte> fileBytes = new(fileSizeInBytes);

   long offset = 0;
   long blockSizeDownload = 4 * 1024 * 1024; // 4 MB

   // File size may be smaller than defined block size
   if (fileSizeInBytes < blockSizeDownload)
   {
         blockSizeDownload = fileSizeInBytes;
   }

   while (fileSizeInBytes > 0)
   {
         // Prepare the request
         DownloadBlockRequest downLoadBlockRequest = new()
         {
            BlockLength = blockSizeDownload,
            FileContinuationToken = fileContinuationToken,
            Offset = offset
         };

         // Send the request
         var downloadBlockResponse =
                  (DownloadBlockResponse)service.Execute(downLoadBlockRequest);

         // Add the block returned to the list
         fileBytes.AddRange(downloadBlockResponse.Data);

         // Subtract the amount downloaded,
         // which may make fileSizeInBytes < 0 and indicate
         // no further blocks to download
         fileSizeInBytes -= (int)blockSizeDownload;
         // Increment the offset to start at the beginning of the next block.
         offset += blockSizeDownload;
   }

   return (fileBytes.ToArray(), fileName);
}

Weitere Informationen:

Anmerkungsdateien

Eine Notiz ist ein Datensatz, der einer Tabellenzeile zugeordnet ist, die Text enthält und an die möglicherweise eine einzelne Datei angehängt ist. Nur Tabellen, bei denen EntityMetadata.HasNotes auf true gesetzt ist, können mit Notizen verknüpft werden.

Hochladen von Anmerkungsdateien

Verwenden Sie die InitializeAnnotationBlocksUpload-, UploadBlock- und CommitAnnotationBlocksUpload-Meldungen, um Dateien für Notizen hochzuladen.

Die Anmerkung, die Sie als Target-Parameter für diese Meldungen übergeben, muss einen annotationid-Wert haben. So können Sie vorhandene Anmerkungsdatensätze aktualisieren.

Normalerweise ist es am besten, die eindeutigen Kennzeichnungswerte beim Erstellen neuer Datensätze von Dataverse generieren zu lassen, aber das ist bei diesen Nachrichten nicht möglich. Um eine neue Anmerkung mit diesen Nachrichten zu erstellen, müssen Sie einen neuen Guid-Wert erstellen, den Sie als annotationid-Wert festlegen, anstatt den Wert von Dataverse generieren zu lassen.

Die folgende statische Methode UploadNote zeigt, wie Sie mit den Klassen InitializeAnnotationBlocksUploadRequest, UploadBlockRequest und CommitAnnotationBlocksUploadRequest eine Notiz mit einer Datei erstellen oder aktualisieren können. Es gibt eine CommitAnnotationBlocksUploadResponse mit den Eigenschaften AnnotationId und FileSizeInBytes zurück.

static CommitAnnotationBlocksUploadResponse UploadNote(
   IOrganizationService service,
   Entity annotation,
   FileInfo fileInfo,
   string? fileMimeType = null)
{

   if (annotation.LogicalName != "annotation")
   {
         throw new ArgumentException(
            message: "The annotation parameter must be an annotation entity",
            paramName: nameof(annotation));
   }
   if (!annotation.Attributes.Contains("annotationid") || annotation.Id != Guid.Empty)
   {
         throw new ArgumentException(
            message: "The annotation parameter must include a valid annotationid value.",
            paramName: nameof(annotation));
   }

   // documentbody value in annotation not needed. Remove if found.
   if (annotation.Contains("documentbody"))
   {
         annotation.Attributes.Remove("documentbody");
   }

   // Try to get the mimetype if not provided.
   if (string.IsNullOrEmpty(fileMimeType))
   {
         var provider = new FileExtensionContentTypeProvider();

         if (!provider.TryGetContentType(fileInfo.Name, out fileMimeType))
         {
            fileMimeType = "application/octet-stream";
         }
   }
   // Don't override what might be included in the annotation.
   if (!annotation.Contains("mimetype")) {
         annotation["mimetype"] = fileMimeType;
   }
   
   // Initialize the upload
   InitializeAnnotationBlocksUploadRequest initializeRequest = new()
   {
         Target = annotation
   };

   var initializeResponse =
         (InitializeAnnotationBlocksUploadResponse)service.Execute(initializeRequest);

   string fileContinuationToken = initializeResponse.FileContinuationToken;

   // Capture blockids while uploading
   List<string> blockIds = new();

   using Stream uploadFileStream = fileInfo.OpenRead();

   int blockSize = 4 * 1024 * 1024; // 4 MB

   byte[] buffer = new byte[blockSize];
   int bytesRead = 0;

   long fileSize = fileInfo.Length;

   // The number of iterations that will be required:
   // int blocksCount = (int)Math.Ceiling(fileSize / (float)blockSize);
   int blockNumber = 0;

   // While there is unread data from the file
   while ((bytesRead = uploadFileStream.Read(buffer, 0, buffer.Length)) > 0)
   {
         // The file or final block may be smaller than 4MB
         if (bytesRead < buffer.Length)
         {
            Array.Resize(ref buffer, bytesRead);
         }

         blockNumber++;
         // Generates base64 string blockId values based on a Guid value so they are always the same length.
         string blockId = Convert.ToBase64String(Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

         blockIds.Add(blockId);

         // Prepare the request
         UploadBlockRequest uploadBlockRequest = new()
         {
            BlockData = buffer,
            BlockId = blockId,
            FileContinuationToken = fileContinuationToken,
         };

         // Send the request
         service.Execute(uploadBlockRequest);
   }

   // Commit the upload
   CommitAnnotationBlocksUploadRequest commitRequest = new()
   {
         BlockList = blockIds.ToArray(),
         FileContinuationToken = fileContinuationToken,
         Target = annotation
   };

      return  (CommitAnnotationBlocksUploadResponse)service.Execute(commitRequest);
}

Weitere Informationen:

Hinweis

Diese Beispielmethode enthält eine Logik, mit der versucht wird, den MIME Typ der Datei mit Hilfe der Methode FileExtensionContentTypeProvider.TryGetContentType(String, String) zu ermitteln, wenn er nicht bereitgestellt wird. Wenn der Typ nicht gefunden wird, wird er auf application/octet-stream gesetzt.

Herunterladen von Anmerkungsdateien

Sie können eine Notizdatei in einem einzigen Vorgang über die Web-API oder in Stücken über das SDK oder die Web-API herunterladen.

Laden Sie Anmerkungsdateien in einem einzigen Vorgang über die Web-API herunter

Mit Hilfe der Web-API können Sie eine Notizdatei in einem einzigen Vorgang herunterladen:

Anders als beim Abrufen von Dateispalten liefert diese Methode keine Informationen über die Dateigröße, den Dateinamen oder den MIME Typ.

Anforderung:

GET [Organization Uri]/api/data/v9.2/annotations(<annotationid>)/documentbody/$value HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: text/plain

<Base64 string content removed for brevity>

Weitere Informationen:

Download von Anmerkungsdateien in Stücken

Um die Datei in Stücken abzurufen, verwenden Sie die folgenden Nachrichten entweder mit dem SDK oder der Web-API:

Nachricht Beschreibung
InitializeAnnotationBlocksDownload Gibt den Datensatz der Notiz an, von dem Sie eine Datei herunterladen möchten. Sie gibt die Dateigröße in Bytes und ein file continuation token zurück, mit dem Sie die Datei blockweise über die DownloadBlock-Nachricht herunterladen können.
DownloadBlock Fordert die Größe des Blocks, den Offset-Wert und das Dateifortsetzungs-Token an.

Nachdem Sie alle Blöcke heruntergeladen haben, fügen Sie sie zusammen, um die gesamte heruntergeladene Datei zu erstellen.

Die folgende statische DownloadNote-Methode zeigt, wie Sie eine Notiz unter Verwendung des SDK mit den Klassen InitializeAnnotationBlocksDownloadRequest und DownloadBlockRequest herunterladen. Diese Funktion gibt die byte[]-Daten und den Namen der Datei zurück.

static (byte[] bytes, string fileName) DownloadNote(
    IOrganizationService service,
    EntityReference target)
{
if (target.LogicalName != "annotation")
{
      throw new ArgumentException("The target parameter must refer to an note record.", nameof(target));
}

InitializeAnnotationBlocksDownloadRequest initializeRequest = new()
{
      Target = target
};

var response =
      (InitializeAnnotationBlocksDownloadResponse)service.Execute(initializeRequest);

string fileContinuationToken = response.FileContinuationToken;
int fileSizeInBytes = response.FileSizeInBytes;
string fileName = response.FileName;

List<byte> fileBytes = new(fileSizeInBytes);

long offset = 0;
long blockSizeDownload = 4 * 1024 * 1024; // 4 MB

// File size may be smaller than defined block size
if (fileSizeInBytes < blockSizeDownload)
{
      blockSizeDownload = fileSizeInBytes;
}

while (fileSizeInBytes > 0)
{
      // Prepare the request
      DownloadBlockRequest downLoadBlockRequest = new()
      {
            BlockLength = blockSizeDownload,
            FileContinuationToken = fileContinuationToken,
            Offset = offset
      };

      // Send the request
      var downloadBlockResponse =
                  (DownloadBlockResponse)service.Execute(downLoadBlockRequest);

      // Add the block returned to the list
      fileBytes.AddRange(downloadBlockResponse.Data);

      // Subtract the amount downloaded,
      // which may make fileSizeInBytes < 0 and indicate
      // no further blocks to download
      fileSizeInBytes -= (int)blockSizeDownload;
      // Increment the offset to start at the beginning of the next block.
      offset += blockSizeDownload;
}

return (fileBytes.ToArray(), fileName);
}

Weitere Informationen:

Begrenzungen der Dateigröße

Die Spalte Organization.MaxUploadFileSize gibt die maximal zugelassene Größe einer Datei in Bytes für einen Anhang und eine Notiz sowie andere Arten von Daten an, wie z.B. Web-Ressourcendateien, die für modellbasierte Apps verwendet werden. Die maximale Upload-Dateigröße gilt für die Größe der Datei in Base64-Codierung. Eine Base64-Kodierung erzeugt eine Zeichenfolge, die größer ist als die ursprünglichen byte[]-Dateidaten.

Die Standardgröße beträgt 5 MB (5.242.880 Bytes) und der Höchstwert beträgt 128 MB (131.072.000 Bytes) und kann in den E-Mail-Einstellungen für die Umgebung festgelegt werden. Weitere Informationen: E-Mail-Einstellungen verwalten

Wenn Sie versuchen, eine zu große Datei hochzuladen, erhalten Sie die folgende Fehlermeldung:

Name: unManagedidsattachmentinvalidfilesize
Code: 0x80044a02
Nummer: -2147202558
Meldung: Attachment file size is too big.

Maximale Dateigröße für Uploads abrufen

Sie können die maximale Dateigröße für den Upload auf verschiedene Weise abrufen.

Verwenden Sie eine statische Methode wie die folgende GetMaxUploadFileSize, um den Wert abzurufen.

public static int GetMaxUploadFileSize(IOrganizationService service) {

   QueryExpression query = new("organization") { 
         ColumnSet = new ColumnSet("maxuploadfilesize")
   };

   EntityCollection organizations = service.RetrieveMultiple(query);

   // There is only one row in organization table
   return (int)organizations.Entities.FirstOrDefault()["maxuploadfilesize"];
}

Weitere Informationen:

Maximale Dateigröße für den Upload ändern

Sie können den Wert organization.maxuploadfilesize auf verschiedene Weise festlegen.

Verwenden Sie eine statische Methode wie die folgende SetMaxUploadFileSize, um die maximale Dateigröße für den Upload festzulegen.

public static void SetMaxUploadFileSize(
    IOrganizationService service, 
    int maxUploadFileSizeInBytes)
{
   if (maxUploadFileSizeInBytes > 131072000 || maxUploadFileSizeInBytes < 1) {
         throw new ArgumentOutOfRangeException(nameof(maxUploadFileSizeInBytes), 
         "The maxUploadFileSizeInBytes parameter must be less than 131072000 bytes and greater than 0 bytes.");
   }

   QueryExpression query = new("organization")
   {
         ColumnSet = new ColumnSet("organizationid")
   };

   EntityCollection organizations = service.RetrieveMultiple(query);

   // There is only one row in organization table
   Entity organization = organizations.Entities.FirstOrDefault();
   organization["maxuploadfilesize"] = maxUploadFileSizeInBytes;

   service.Update(organization);
}

Weitere Informationen:

Siehe auch

Dateien und Bilder – Übersicht
Beispiel: Dateivorgänge mit Anlagen und Notizen unter Verwendung des Dataverse SDK für .NET
Beispiel: Dateivorgänge für Anlagen und Anmerkungen mit Dataverse Web-API

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).