Freigeben über

Dateidaten mit Anlagen- und Notizdatensätzen verwenden

Anhangtabellen (ActivityMimeAttachment) und Notiztabellen (Annotation) 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 Anlagen- oder Notizdatensatz sind, aktualisieren Sie diese vier Spalten zusammen mit allen anderen Werten.

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öhen und mit größeren Dateien arbeiten, verwenden Sie die bereitgestellten Nachrichten, um die Dateien beim Hochladen oder Herunterladen von Dateien in kleinere Abschnitte 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). Sie können der Aktivität oder Vorlage mehrere Anlagen zuordnen. 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

Verwechseln Sie attachment (ActivityMimeAttachment) nicht mit activityfileattachment, das Dateien unterstützt, die der Post-Tabelle zugeordnet sind.

Innerhalb des Dataverse-Schemas gibt es auch eine öffentliche Tabelle mit dem Namen Attachment, die in der Web-API als attachment EntityType angezeigt wird. Sie können diese Tabelle abfragen und sie spiegelt die Daten der ActivityMimeAttachment Tabelle wider. Sie unterstützt jedoch keine Erstellen-, Abrufen-, Aktualisieren- oder Löschvorgä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 eine Anlage mit einer Datei mithilfe der Klassen InitializeAttachmentBlocksUploadRequest, UploadBlockRequest und CommitAttachmentBlocksUploadRequest erstellen, um ein 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 finden Sie unter:

Notiz

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 Anlagendatei in einem einzelnen Vorgang mithilfe der Web-API oder in Blöcken mithilfe des SDK oder der Web-API herunterladen.

Herunterladen von Anhängen in einem Schritt mithilfe der 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 finden Sie unter:

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 finden Sie unter:

Anmerkungsdateien

Eine Notiz ist ein Datensatz, der einer Tabellenzeile zugeordnet ist, die Text enthält und eine angefügte Datei aufweisen kann. Nur Tabellen, bei denen EntityMetadata.HasNotes auf „true“ gesetzt ist, unterstützen zugehörige Notizen.

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. Mit diesem Wert aktualisieren Sie vorhandene Anmerkungsdatensätze.

Normalerweise lassen Sie Dataverse beim Erstellen neuer Datensätze die eindeutigen Bezeichnerwerte generieren, aber mit diesen Nachrichten ist das nicht möglich. Um eine neue Anmerkung mithilfe dieser Nachrichten zu erstellen, generieren Sie einen neuen Guid-Wert, den Sie als annotationid-Wert festlegen, anstatt Dataverse den Wert generieren zu lassen.

Die folgende statische UploadNote Methode zeigt, wie Sie eine Notiz mit einer Datei mithilfe der InitializeAnnotationBlocksUploadRequestKlassen UploadBlockRequestCommitAnnotationBlocksUploadRequest erstellen oder aktualisieren. 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 finden Sie unter:

Notiz

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 Schritt mithilfe der Web-API oder in Blöcken mithilfe des SDK oder der Web-API herunterladen.

Herunterladen von Anmerkungsdateien in einem einzigen Schritt mithilfe der Web-API

Mithilfe der Web-API können Sie eine Notizdatei in einem einzigen Schritt 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 finden Sie unter:

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 Byte und ein Dateifortsetzungstoken zurück, mit dem Sie die Datei mithilfe der DownloadBlock Nachricht in Blöcken 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 mithilfe 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 finden Sie unter:

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 modellgesteuerte 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 Maximalwert beträgt 128 MB (131.072.000 Bytes). Sie können diesen Wert in den E-Mail-Einstellungen für die Umgebung festlegen. Weitere Informationen erhalten Sie unter E-Mail-Einstellungen verwalten.

Wenn Sie versuchen, eine datei hochzuladen, die zu groß ist, wird die folgende Fehlermeldung angezeigt:

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 Methode, 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 finden Sie unter:

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

Legen Sie den organization.maxuploadfilesize Wert auf verschiedene Arten fest.

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 finden Sie unter:

Siehe auch

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

  • Last updated on