Algorytm C#, klasa DocumentAttachmentsHelper

Wersja nAxiom 1.15.0.0, data publikacji: 2025-09-09

Przeczytasz w 11 min.

Wprowadzanie
Typy danych
Opis metod

Wprowadzanie

Akcja algorytmu C# oferuje metody umożliwiające zarządzanie załącznikami instancji dokumentu. Są one zdefiniowane w klasie DocumentAttachmentsHelper:

RemoveAttachment: usuwa załącznik (wszystkie wersje)
RemoveAttachmentVersion: usuwa wskazaną wersję załącznika
GetAttachment: pobiera dane załącznika bez zawartości binarnej
GetAttachmentWithFileContent: pobiera dane załącznika z zawartością binarną
GetAttachments: pobiera listę wszystkich najnowszych wersji załączników ze wskazanej instancji dokumentu lub kategorii załączników (bez zawartości binarnej),
GetAttachmentsByVersioningIdentifier: pobiera listę załączników dla wskazanego identyfikatora wersjonowania
UploadAttachment: dodaje lub nadpisuje załącznik
SetAttachmentDescription: ustawia opis załącznika (wersji załącznika w przypadku włączonego wersjonowania załączników)

Odpowiedzi zwracane przez metody są opakowane w generyczną klasę RequestResponse<T> o właściwościach:

IsValid: flaga poprawnego wykonania operacji
Result: dane o typie zgodnym z typem przekazanym do wywołania RequestResponse
ValidationResult: informacje o błędach w przypadku niepowodzenia wykonania akcji

Typy danych

AttachmentData: dane załącznika bez zawartości binarnej

record AttachmentData
     (int Id,
     string RecordId,
     int BusinessDocumentId,
     string FileName,
     long FileSize,
     string Description,
     Guid VersioningIdentifier,
     int VersionNumber,
     Guid RowGuid,
     int AttachmentCategoryId,
     Guid UserId,
     DateTime CreatedDate,
     Guid ModifyUserId,
     DateTime ModifyDate);

AttachmentDataWithContent: dane załącznika z zawartością binarną.

record AttachmentDataWithContent(byte[] FileContent, AttachmentData Attachment);

GetAttachmentsRequest: klasa żądania pobrania listy załączników.

class GetAttachmentsRequest
{
 public int BusinessDocumentId { get; set; }
 public string RecordId { get; set; } = string.Empty;

 public int? AttachmentCategoryId { get; set; }
}

GetAttachmentsByVersioningIdentifierRequest: klasa żądania pobrania listy załączników dla wskazanego identyfikatora wersjonowania.

class GetAttachmentsByVersioningIdentifierRequest
{
 public int BusinessDocumentId { get; set; }
 public string RecordId { get; set; } = string.Empty;
 public Guid VersioningIdentifier { get; set; }
}

UploadAttachmentRequest: klasa żądania dodania lub nadpisania załącznika.

class UploadAttachmentRequest
{
 public string RecordId { get; set; }
 public int BusinessDocumentId { get; set; }
 public int? AttachmentCategoryId { get; set; }
 public string FileName { get; set; }
 public string Description { get; set; }
 public byte[] FileContent { get; set; }
 public bool Overwrite { get; set; }
}

SetAttachmentDescriptionRequest: klasa żądania ustawienia opisu załącznika.

class SetAttachmentDescriptionRequest
{
 public int AttachmentId { get; set; }
 public string Description { get; set; }
}

Opis metod

RemoveAttachment: pozwala na usunięcie wskazanego załącznika i wszystkich jego wersji. Należy przekazać identyfikator dowolnej wersji załącznika. Rezultatem jest bool.
Przykład użycia:

using System;
using System.Linq;
using System.Text;
using Shared.Exceptions;
using CSharpScript.Attachments;
using CSharpScript.ActionRunner;
using CSharpScript.SqlRunner;
using CSharpScript.WebServiceRunner;
using CSharpScript.WebServiceRunner.Models;
// Some calculated attachment ID
var attachmentId = 8;
var removeAttachmentResponse = await DocumentAttachmentsHelper.RemoveAttachment(attachmentId);
if (!removeAttachmentResponse.IsValid)
{
  throw new TranslatedException(
 $"Usunięcie załącznika o identyfikatorze {attachmentId} zakończyło się błędem.",
 removeAttachmentResponse.ValidationResult);
}

RemoveAttachmentVersion: pozwala na usunięcie wskazanej wersji załącznika. Rezultatem jest bool.
Przykład użycia:

 using System;
 using System.Linq;
 using System.Text;
 using Shared.Exceptions;
 using CSharpScript.Attachments;
 using CSharpScript.ActionRunner;
 using CSharpScript.SqlRunner;
 using CSharpScript.WebServiceRunner;
 using CSharpScript.WebServiceRunner.Models;

 // Some calculated attachment ID
 var attachmentId = 8;

 var removeAttachmentVersionResponse = await DocumentAttachmentsHelper.RemoveAttachmentVersion(attachmentId);

 if (!removeAttachmentVersionResponse.IsValid)
 {
 throw new TranslatedException(
     $"Usunięcie wersji załącznika o identyfikatorze {attachmentId} zakończyło się błędem.",
     removeAttachmentVersionResponse.ValidationResult);
 }

GetAttachment: pobiera informacje o załączniku bez jego zawartości binarnej. Rezultatem jest AttachmentData.
Przykład użycia:

 using System;
 using System.Linq;
 using System.Text;
 using Shared.Exceptions;
 using CSharpScript.Attachments;
 using CSharpScript.ActionRunner;
 using CSharpScript.SqlRunner;
 using CSharpScript.WebServiceRunner;
 using CSharpScript.WebServiceRunner.Models;

 // Some calculated attachment ID
 var attachmentId = 8;

 var getAttachmentResponse = await DocumentAttachmentsHelper.GetAttachment(attachmentId);

 if (!getAttachmentResponse.IsValid)
 {
 throw new TranslatedException(
     $"Pobieranie załącznika o identyfikatorze {attachmentId} zakończyło się błędem.",
     getAttachmentResponse.ValidationResult);
 }

 if (string.IsNullOrEmpty(getAttachmentResponse.Result.Description))
 {
 throw new TranslatedException("Plik nie posiada wymaganego opisu.");
 }

GetAttachmentWithFileContent: pobiera załącznik z jego zawartością binarną w formie strumienia danych. Rezultatem jest AttachmentDataWithContent.
Przykład użycia:

 using System;
 using System.Linq;
 using System.Text;
 using System.IO;
 using Shared.Exceptions;
 using CSharpScript.Attachments;
 using CSharpScript.ActionRunner;
 using CSharpScript.SqlRunner;
 using CSharpScript.WebServiceRunner;
 using CSharpScript.WebServiceRunner.Models;

 // Some calculated attachment ID
 var attachmentId = 8;

 var getAttachmentResponse = await DocumentAttachmentsHelper.GetAttachmentWithFileContent(attachmentId);

 if (!getAttachmentResponse.IsValid)
 {
 throw new TranslatedException(
     $"Pobieranie załącznika o identyfikatorze {attachmentId} zakończyło się błędem.",
     getAttachmentResponse.ValidationResult);
 }

 File.WriteAllBytes(Path.Combine(@"C:/Attachments", getAttachmentResponse.Result.FileName), getAttachmentResponse.Result.FileContent);

GetAttachments: pobiera listę najnowszych wersji wszystkich załączników dokumentu lub w danej kategorii. Parametrem jest GetAttachmentsRequest. Rezultatem jest IReadOnlyList<AttachmentData>.
Przykład użycia:

 using System;
 using System.Linq;
 using System.Text;
 using Shared.Exceptions;
 using CSharpScript.Attachments;
 using CSharpScript.ActionRunner;
 using CSharpScript.SqlRunner;
 using CSharpScript.WebServiceRunner;
 using CSharpScript.WebServiceRunner.Models;

 // Some attachment category ID
 var attachmentCategoryId = 8;
 var expectedAttachmentsCount = 3;

 var getAttachmentsResponse = await DocumentAttachmentsHelper.GetAttachments(
 new GetAttachmentsRequest
 {
     BusinessDocumentId = BusinessDocumentId.Value,
     RecordId = RecordId,
     AttachmentCategoryId = attachmentCategoryId  // optional
 });

 if (!getAttachmentsResponse.IsValid)
 {
 throw new TranslatedException(
     $"Pobieranie załączników zakończyło się błędem.",
     getAttachmentsResponse.ValidationResult);
 }

 if (getAttachmentsResponse.Result.Count < expectedAttachmentsCount)
 {
 throw new TranslatedException($"Brak wymaganej ilości załączników w liczbie {expectedAttachmentsCount}.");
 }

GetAttachmentsByVersioningIdentifier: pobiera listę wszystkich wersji załączników dla danego identyfikatora wersjonowania. Parametrem jest GetAttachmentsByVersioningIdentifierRequest. Rezultatem jest IReadOnlyList<AttachmentData>.
Przykład użycia:

 using System;
 using System.Linq;
 using System.Text;
 using Shared.Exceptions;
 using CSharpScript.Attachments;
 using CSharpScript.ActionRunner;
 using CSharpScript.SqlRunner;
 using CSharpScript.WebServiceRunner;
 using CSharpScript.WebServiceRunner.Models;

 // Some calculated attachment ID
 var attachmentId = 8;

 var getAttachmentResponse = await DocumentAttachmentsHelper.GetAttachment(attachmentId);

 if (!getAttachmentResponse.IsValid)
 {
 throw new TranslatedException(
     $"Pobieranie załącznika o identyfikatorze {attachmentId} zakończyło się błędem.",
     getAttachmentResponse.ValidationResult);
 }

 var getAttachmentsResponse = await DocumentAttachmentsHelper.GetAttachmentsByVersioningIdentifier(
 new GetAttachmentsByVersioningIdentifierRequest
 {
     BusinessDocumentId = BusinessDocumentId.Value,
     RecordId = RecordId,
     VersioningIdentifier = getAttachmentResponse.Result.VersioningIdentifier
 });

 if (!getAttachmentsResponse.IsValid)
 {
 throw new TranslatedException(
     $"Pobieranie załączników dla wskazanego identyfikatora wersjonowania zakończyło się błędem.",
     getAttachmentsResponse.ValidationResult);
 }

 foreach (var attachment in getAttachmentsResponse.Result)
 {
 // Działania na liście załączników
 }

UploadAttachment: dodaje nowy załącznik lub nadpisuje istniejący. Parametrem jest UploadAttachmentRequest. Rezultatem jest AttachmentData.
Przykład użycia:

 using System;
 using System.Linq;
 using System.Text;
 using System.IO;
 using Shared.Exceptions;
 using CSharpScript.Attachments;
 using CSharpScript.ActionRunner;
 using CSharpScript.SqlRunner;
 using CSharpScript.WebServiceRunner;
 using CSharpScript.WebServiceRunner.Models;

 var attachmentUploadResponse = await DocumentAttachmentsHelper.UploadAttachment(
     new UploadAttachmentRequest
     {
         RecordId = RecordId,
         BusinessDocumentId = BusinessDocumentId.Value,
         AttachmentCategoryId = null, // Default attachment category
         FileName = "TestFile.txt",
         Description = "My Test File",
         FileContent = File.ReadAllBytes(Path.Combine(@"C:/Attachments", "TestFile.txt")),
         Overwrite = false
     });
        
 if (!attachmentUploadResponse.IsValid)
 {
 throw new TranslatedException(
     $"Błąd dodawania załącznika do dokumentu.",
     attachmentUploadResponse.ValidationResult);
 }

Opcja nadpisywania załącznika wymaga, aby załącznik, który jest nadpisywany miał taką samą nazwę jak załącznik przesyłany w żądaniu. W przypadku, gdy załącznik nie zostanie odnaleziony zostanie zwrócony błąd o braku załącznika.

Ponadto w przypadku nadpisywania załącznika lub dodawania nowej wersji załącznika nie można zmienić opisu.

SetAttachmentDescription: ustawia opis dla wskazanej wersji załącznika. Parametrem jest SetAttachmentDescriptionRequest. Rezultatem jest bool.

Przykład użycia:

 using System;
 using System.Linq;
 using System.Text;
 using Shared.Exceptions;
 using CSharpScript.Attachments;
 using CSharpScript.ActionRunner;
 using CSharpScript.SqlRunner;
 using CSharpScript.WebServiceRunner;
 using CSharpScript.WebServiceRunner.Models;

 // Some calculated attachment ID
 var attachmentId = 8;

 var setAttachmentDescriptionResponse = await DocumentAttachmentsHelper.SetAttachmentDescription(
 new SetAttachmentDescriptionRequest
 {
     AttachmentId = attachmentId,
     Description = "New file description"
 });

 if (!setAttachmentDescriptionResponse.IsValid)
 {
 throw new TranslatedException(
     $"Ustawienie opisu załącznika o identyfikatorze {attachmentId} zakończyło się błędem.",
     setAttachmentDescriptionResponse.ValidationResult);
 }