Ana içeriğe geç

RelatedDocuments

Forma dosya ekleyip ilişkili belgeleri liste halinde gösteren nesnedir. Kullanıcı; sözleşme, fatura, teklif gibi belgeleri yükler ya da Doküman Yönetimi'nden seçer, eklenen dosyalar nesnenin içinde kategorileriyle birlikte görünür.

Bu nesne CompositeDataBoundControl türünden gelir; bir TextBox gibi tek bir Value/Text değeri yoktur. Eklenen dosyalar Files listesinde (List<RelatedDocumentFile>) tutulur ve dosya ekleme/silme/indirme işlemleri için zengin bir metot kümesi sunar.

Ne zaman kullanılır?

Bir kayda birden çok dosya iliştirmek istediğinizde kullanın: satınalma talebine teklifler, izin formuna rapor, sözleşmeye ekler. Tek bir dosya alanı yeterliyse FileSelector daha hafiftir. RelatedDocuments birden çok belgeyi kategori, açıklama ve OCR desteğiyle yönetir; ayrıca koddan dosya ekleme, silme ve indirme metotlarına sahiptir.

Tasarımcı özellikleri

Bir RelatedDocuments seçildiğinde Özellik Görüntüleyici sekmelere ayrılır.

General

ÖzellikAçıklama
NameNesnenin koddaki adı (ör. RelatedDocuments1). Koddan bu adla erişirsiniz.

Behavior

ÖzellikAçıklama
AddingModeBelge ekleme biçimini belirler. Enum RelatedDocumentsAddingMode: Local (bilgisayardan yükleme), DM (Doküman Yönetimi'nden seçme), All (ikisi de).
AddNewEnabledYeni dosya ekleme düğmesini açar veya kapatır.
AdvancedEditGelişmiş düzenleme seçeneklerini etkinleştirir.
CategoriesBelgelerin atanabileceği kategorilerin listesi (List<RelatedDocumentCategory>).
CreateEnabledYeni belge oluşturmaya izin verir.
DeleteEnabledEklenen belgenin silinebilmesini sağlar.
EnabledOCRYüklenen belgelerde OCR (metin tanıma) işlemini açar.
FileDescriptionIsRequiredDosya açıklamasını zorunlu yapar.
PathBelgelerin kaydedileceği DM klasör yolu.
ReadOnlyNesneyi salt okunur yapar; yeni dosya eklenemez, silinemez.
RequiredEn az bir belge eklenmesini zorunlu kılar; boşsa form kaydedilmez.
ShowCategoryDescriptionKategori açıklamasını gösterir.
ShowContentForImageFilesResim dosyalarının önizlemesini gösterir.
ShowCreateDateBelgenin oluşturulma tarihini sütun olarak gösterir.
ShowCreatorBelgeyi ekleyen kullanıcıyı gösterir.
ShowFileDescriptionDosya açıklaması sütununu gösterir.
ShowFileExtensionDosya uzantısını gösterir.
ShowPathDosyanın saklandığı yolu gösterir.
ViewableBelgelerin görüntülenebilmesini sağlar.
ViewTypeListenin görünüm biçimi. Enum RelatedDocumentsViewType: Card, List, Compact, Button.
IndexableNesnenin içeriğinin indekslenip indekslenmeyeceği.

Appearance

ÖzellikAçıklama
Visible / Client VisibleNesnenin görünürlüğü.
Enabled / Client EnabledNesnenin aktif olup olmadığı.
TitleNesnenin başlığı (MultiLanguageText, çok dilli olabilir).
CaptionEtiket bilgisi (ControlCaption).
Style / Container StyleNesnenin ve kapsayıcısının stili.
Custom Class NameÖzel CSS sınıf adı.
Bu nesnenin değeri yoktur

RelatedDocuments EditControl türünden gelmez; bu yüzden Value, Text, Placeholder ve Text Align gibi özellikleri yoktur. Bir TextBox'tan farklı olarak değer okumak/yazmak yerine Files listesi ve dosya metotlarıyla çalışırsınız.

Olaylar

RelatedDocuments'ın kendine özgü olayları, kullanıcı dosya ekleyip çıkardıkça tetiklenen dosya olaylarıdır. Bu nesnede metin/değer değişim olayı (TextChanged, ValueChanged vb.) yoktur; çünkü bir değeri yoktur.

Kullanıcı dosya eklerken: BeforeFileAddAfterFileAdd, dosya silerken BeforeFileRemoveAfterFileRemove

Sunucu olayları (Server)

Tüm dosya olayları sunucu tarafında C# kodunda yazılır. Olay işleyicisinin imzasındaki argüman tipi Add ile Remove tarafında farklıdır.

OlayArgüman tipiNe zaman çalışır
BeforeFileAddRelatedDocumentsAddEventArgsBir veya daha fazla dosya eklenmeden hemen önce. İptal edilemez.
AfterFileAddRelatedDocumentsAddEventArgsDosya(lar) eklendikten hemen sonra. En sık kullanılan olaydır.
BeforeFileRemoveRelatedDocumentsRemoveEventArgsBir dosya silinmeden hemen önce. e.Cancel = true ile iptal edilebilir.
AfterFileRemoveRelatedDocumentsRemoveEventArgsDosya silindikten hemen sonra.
ValidatingEventValidatingEventArgsNesne doğrulanırken (salt okunur olay; += ile bağlanır).
Olay argümanlarının asimetrisi

Add tarafı ile Remove tarafı aynı şekli taşımaz, bu yüzden imzayı kopyalarken dikkat edin:

  • RelatedDocumentsAddEventArgs (BeforeFileAdd / AfterFileAdd): List<RelatedDocumentFile> Files (eklenen dosyaların listesi) ve ResponseParameters. Cancel özelliği yoktur, dolayısıyla BeforeFileAdd ile ekleme engellenemez.
  • RelatedDocumentsRemoveEventArgs (BeforeFileRemove / AfterFileRemove): Boolean Cancel, RelatedDocumentFile File (silinen tek dosya) ve ResponseParameters. Yalnızca burada Cancel vardır; BeforeFileRemove içinde e.Cancel = true yaparak silmeyi durdurabilirsiniz.

Eklemeyi uzantı/boyut bazında kısıtlamak istiyorsanız BeforeFileAdd yerine Categories içindeki AllowedFileExtensions, MaxFileSize, MaxFilesCount ayarlarını kullanın.

İlgili tip şekilleri

Dosyalarla çalışan örnekleri kullanabilmek için listedeki ve metotlardaki tiplerin üyelerini bilmeniz gerekir.

RelatedDocumentFile (Files listesinin elemanı):

ÜyeTipAçıklama
IdStringDM nesne kimliği (metin olarak).
NameStringDosya adı.
DescriptionStringDosya açıklaması.
ExtensionStringUzantı (ör. "pdf").
FileSizeInt64Bayt cinsinden boyut.
PathStringDosyanın DM yolu.
SecretKeyStringDM gizli anahtarı (indirme URL'si için).
DownloadUrlStringİndirme yolu.
DataByte[]Dosya içeriği (bayt dizisi).
CategoryRelatedDocumentCategoryDosyanın atandığı kategori.
CreateDateNullable<DateTimeOffset>Oluşturulma tarihi.
Creator / CreatorIdString / Int64Ekleyen kullanıcı.
OCRDataStringOCR çıktısı (EnabledOCR açıksa).

RelatedDocumentCategory (Categories ve RelatedDocumentFile.Category):

ÜyeTipAçıklama
IdInt64Kategori kimliği.
CategoryIdStringKategorinin GUID metni.
Name / DescriptionDictionary<String,String>Dil → metin sözlüğü.
AllowedFileExtensionsList<String>İzin verilen uzantılar (boş liste = her tür).
MaxFilesCountNullable<Int32>En fazla dosya (null = sınırsız).
MaxFileSizeNullable<Int64>En büyük boyut (null = sınırsız).
MinFilesCountInt32En az dosya sayısı.
PathStringKategorinin DM yolu.

RDUploadFile (yükleme için AddFileByUpload / UploadFile): Data (Byte[]), MimeType (String), Name (Dictionary<String,String>), Description (Dictionary<String,String>).

RDDownloadedFile (DownloadFile döner): Data (Byte[]), FileId (Int64), Name / Description (Dictionary<String,String>), MimeType, DownloadUrl, SecretKey.

Metotlar

RelatedDocuments koddan dosya yönetmek için zengin bir metot kümesi sunar. Async metotlar Task<...> döner; sunucu kodunda .Result ile veya await ile çalıştırılır.

MetotİmzaAçıklama
AddFileBoolean AddFile(RelatedDocumentFile file)Hazır oluşturulmuş bir dosyayı Files'a ekler (senkron).
AddFileByIdTask<Boolean> AddFileById(String categoryId, Int64 fileId)Var olan bir DM dosyasını kimliğiyle bir kategoriye ekler.
AddFileByUploadTask<Boolean> AddFileByUpload(String categoryId, RDUploadFile file)Yeni baytları yükleyerek ekler.
AddFilesByUploadTask<Boolean> AddFilesByUpload(String categoryId, List<RDUploadFile> files)Birden çok dosyayı tek seferde yükler.
UploadFileTask<RDUploadedFile> UploadFile(String path, RDUploadFile file)Belirtilen yola bir dosya yükler.
UploadFilesTask<List<RDUploadedFile>> UploadFiles(String categoryId, List<RDUploadFile> files)Bir kategoriye çoklu yükleme.
RemoveFileTask<Boolean> RemoveFile(Int64 fileId) / RemoveFile(RelatedDocumentFile file)Tek dosyayı siler.
RemoveFilesTask<Boolean> RemoveFiles(List<RelatedDocumentFile> files) / RemoveFiles(List<Int64> files)Çok dosyayı siler.
RemoveAllFilesTask<Boolean> RemoveAllFiles()Tüm dosyaları temizler.
DownloadFileTask<RDDownloadedFile> DownloadFile(Int64 fileId) / DownloadFile(RelatedDocumentFile file)Dosya içeriğini bayt olarak indirir.
DownloadFilesTask<List<RDDownloadedFile>> DownloadFiles(...)Çok dosyayı indirir.
GetObjectsList<RelatedDocumentObject> GetObjects(List<Int64> objectIds, FormHttpParameters p)Dosya meta verilerini döner (içerik yok).
GetObjectsWithSecretKeyList<RelatedDocumentObject> GetObjectsWithSecretKey(List<ObjectSecret> objectSecrets, FormHttpParameters p)Gizli anahtarla meta veri okur.
SetPathVoid SetPath(String path)Nesnenin yazacağı DM yolunu ayarlar.
ApplyChangesVoid ApplyChanges()Bekleyen değişiklikleri uygular.

Kod örnekleri

Bu nesnenin tek bir değeri yoktur; bunun yerine Files listesi ve dosya metotlarıyla çalışırsınız. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz; bu, tipli RelatedDocuments nesnesidir, yani Files zaten List<RelatedDocumentFile> tipindedir:

// Yüklenen dosya sayısını oku
int dosyaSayisi = RelatedDocuments1.Files.Count;

// Nesneyi salt okunur yap
RelatedDocuments1.ReadOnly = true;

// En az bir belge eklenmesini zorunlu kıl
RelatedDocuments1.Required = true;

// Görünümü kart biçimine al
RelatedDocuments1.ViewType = RelatedDocumentsViewType.Card;

Akış (Flow) kodu (C#, sunucu)

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Burada elinizdeki genel Control nesnesidir; bu sapı tipli RelatedDocuments nesnesine dönüştüremezsiniz. Genel Control yalnızca .Text / .Value / .Type / .Rows / GetPropertyValue<T>() üyelerini sunar; ReadOnly, AddNewEnabled gibi davranış özellikleri bu sap üzerinde yoktur. Akış kodunda yapabileceğiniz, .Value'yu okumaktır; bu değer tipli liste değil, bir Newtonsoft JArray olarak gelir:

// Genel Control sapı: yalnızca .Value / .Text / GetPropertyValue<T> erişilir
Control control = Document1.Controls["RelatedDocuments1"];

// Eklenmiş dosyalar JArray olarak .Value içinde gelir
JArray ham = (JArray)control.Value;
int dosyaSayisi = ham?.Count ?? 0;

// Bir özelliği adıyla okumak için GetPropertyValue<T> kullanın
bool ekleAcik = control.GetPropertyValue<bool>("AddNewEnabled");
Davranış özellikleri form kodunda ayarlanır

ReadOnly, AddNewEnabled, Required, ViewType gibi tipli özellikleri yalnızca form (Controller) kodunda doğrudan tipli RelatedDocuments1 nesnesi üzerinden değiştirebilirsiniz (yukarıdaki "Form kodu" örneğine bakın). Akış kodundaki genel Control sapı bu üyeleri sunmaz.

İstemci kodu (TypeScript, tarayıcı)

İstemci tarafında nesnelere this. ile erişilir ve özellik adları küçük harfle yazılır:

// Nesneyi salt okunur yap
this.RelatedDocuments1.readOnly = true;

// Nesneyi gizle
this.RelatedDocuments1.visible = false;

Örnek 1: Eklenen dosyaları okuma (Files üzerinde dolaşma)

Form kodunda Files zaten tipli bir listedir, doğrudan dolaşabilirsiniz:

long toplamBoyut = 0;
foreach (RelatedDocumentFile f in RelatedDocuments1.Files)
{
// Her dosyanın adı, uzantısı, boyutu ve DM yolu doludur
toplamBoyut += f.FileSize;
string ad = f.Name;
string uzanti = f.Extension;
string yol = f.Path;
}

ShowMessage("Bilgi",
RelatedDocuments1.Files.Count + " belge, toplam " + toplamBoyut + " bayt.",
Bimser.CSP.FormControls.RuleManager.AlertType.Info);

Akış kodunda ise elinizdeki genel Control olduğu için .Value'yu JArray olarak okuyup dönüştürmeniz gerekir:

Control control = Document1.Controls["RelatedDocuments1"];
JToken raw = (JToken)control.Value;
if (raw != null && raw.HasValues)
{
List<RelatedDocumentFile> dosyalar =
((JArray)control.Value).ToObject<List<RelatedDocumentFile>>();

foreach (RelatedDocumentFile f in dosyalar)
{
// f.SecretKey, f.Name, f.Path, f.Extension, f.FileSize doludur
}
}

Örnek 2: Dosya eklenince çalıştırma (AfterFileAdd)

AfterFileAdd bir veya daha fazla dosya eklendikten hemen sonra çalışır. Argüman tipi RelatedDocumentsAddEventArgs'tır ve eklenen dosyalara e.Files ile ulaşılır:

void RelatedDocuments1_AfterFileAdd(object sender,
Bimser.CSP.FormControls.Events.RelatedDocumentsAddEventArgs e)
{
// e.Files: yeni eklenen dosyaların listesi
foreach (RelatedDocumentFile f in e.Files)
{
if (f.Extension != null && f.Extension.ToLower() != "pdf")
{
ShowMessage("Uyarı",
f.Name + " PDF değil. Lütfen yalnızca PDF yükleyin.",
Bimser.CSP.FormControls.RuleManager.AlertType.Warning);
}
}

ShowMessage("Bilgi",
"Toplam " + RelatedDocuments1.Files.Count + " belge mevcut.",
Bimser.CSP.FormControls.RuleManager.AlertType.Info);
}
BeforeFileAdd ile ekleme iptal edilemez

RelatedDocumentsAddEventArgs üzerinde Cancel özelliği yoktur; bu yüzden BeforeFileAdd içinde eklemeyi durduramazsınız. Uzantı/boyut kısıtı için Categories içindeki AllowedFileExtensions ve MaxFileSize ayarlarını kullanın, yüklemeden sonra geri bildirim için AfterFileAdd'i kullanın.

Örnek 3: Bir silme işlemini engelleme (BeforeFileRemove + Cancel)

Cancel özelliğinin gerçekten bulunduğu tek yer silme tarafıdır. BeforeFileRemove içinde e.Cancel = true yaparak belirli dosyaların silinmesini durdurabilirsiniz. Argüman tipi RelatedDocumentsRemoveEventArgs'tır ve silinen tek dosya e.File'dadır:

void RelatedDocuments1_BeforeFileRemove(object sender,
Bimser.CSP.FormControls.Events.RelatedDocumentsRemoveEventArgs e)
{
// Sözleşme uzantılı dosyaların silinmesini engelle
if (e.File != null && e.File.Name != null &&
e.File.Name.StartsWith("SOZLESME_"))
{
e.Cancel = true; // silme işlemini iptal eder
ShowMessage("Uyarı",
"Sözleşme belgeleri silinemez.",
Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
}
}

Örnek 4: Koddan dosya ekleme (AddFileByUpload)

Tipli nesneye sahip olduğunuz form kodunda, DM'ye yeni baytlar yükleyerek dosya ekleyebilirsiniz. Metot Task<Boolean> döndüğü için sonucu beklemeniz gerekir:

// data: dosya baytları (byte[])
byte[] data = /* ... DM'den veya üretilen baytlar ... */;

bool eklendi = RelatedDocuments1.AddFileByUpload(
"42ea5d98-87bf-f07a-caa0-ec1fcd8dd701", // hedef kategorinin GUID'i
new RDUploadFile
{
Data = data,
MimeType = "application/pdf",
Name = new Dictionary<string, string> { { "tr-TR", "Sertifika.pdf" } },
Description = new Dictionary<string, string> { { "tr-TR", "Kalite sertifikası" } }
}).Result;

// Var olan bir DM dosyasını kimliğiyle eklemek için:
// RelatedDocuments1.AddFileById("42ea5d98-...", dmFileId).Result;

Akış kodunda yalnızca genel Control elinizdeyse, .Value'yu JArray olarak okuyup elle bir RelatedDocumentFile ekleyip geri yazabilirsiniz:

Control control = form.Controls["RelatedDocuments1"];

// Mevcut listeyi oku (boşsa yeni liste)
List<RelatedDocumentFile> files;
JToken raw = (JToken)control.Value;
if (raw == null || !raw.HasValues)
files = new List<RelatedDocumentFile>();
else
files = ((JArray)control.Value).ToObject<List<RelatedDocumentFile>>();

// Yeni dosyayı kur; Category, nesnenin tanımlı kategorilerinden birine işaret etmeli
files.Add(new RelatedDocumentFile
{
Id = file.Id.ToString(),
Name = "PDF_" + Document1.DocumentId + ".pdf",
Extension = "pdf",
Path = "Projeler/AEP/PDF/PDF_" + Document1.DocumentId + ".pdf",
CreateDate = DateTimeOffset.Now,
Creator = "7",
FileSize = data.Length,
Data = data,
SecretKey = file.SecretKey,
Category = new RelatedDocumentCategory
{
Id = 1,
CategoryId = "42ea5d98-87bf-f07a-caa0-ec1fcd8dd701",
Name = new Dictionary<string, string> { { "tr-TR", "PDF" } },
AllowedFileExtensions = new List<string>(),
Enabled = true,
Path = "Projeler/AEP/PDF"
}
});

// Listeyi geri yaz ve kaydet
control.Value = files;
form.Save();

Örnek 5: Bir dosyayı indirme (DownloadFile)

DownloadFile bir dosyanın baytlarını RDDownloadedFile içinde döner. Listedeki ilk dosyanın içeriğini almak için:

if (RelatedDocuments1.Files.Count > 0)
{
RelatedDocumentFile ilk = RelatedDocuments1.Files[0];

RDDownloadedFile indirilen = RelatedDocuments1.DownloadFile(ilk).Result;
byte[] icerik = indirilen.Data; // dosya baytları
string mimeTuru = indirilen.MimeType;

// icerik ile bir e-postaya ek koyabilir, başka bir DM'ye yazabilirsiniz
}

Örnek 6: Kategori ve görünüm ayarlama (Categories + ViewType)

Belgeleri gruplamak için Categories listesini koddan kurabilir, görünümü ViewType ile değiştirebilirsiniz:

RelatedDocuments1.Categories = new List<RelatedDocumentCategory>
{
new RelatedDocumentCategory
{
Id = 1,
CategoryId = "cat-teklif",
Name = new Dictionary<string, string> { { "tr-TR", "Teklifler" } },
AllowedFileExtensions = new List<string> { "pdf", "docx" },
MaxFileSize = 10485760, // 10 MB
MinFilesCount = 1,
Enabled = true
},
new RelatedDocumentCategory
{
Id = 2,
CategoryId = "cat-fatura",
Name = new Dictionary<string, string> { { "tr-TR", "Faturalar" } },
AllowedFileExtensions = new List<string> { "pdf" },
Enabled = true
}
};

// Belgeleri sıkışık liste biçiminde göster
RelatedDocuments1.ViewType = RelatedDocumentsViewType.Compact;

// Ekleme modunu yalnızca DM'den seçmeye al
RelatedDocuments1.AddingMode = RelatedDocumentsAddingMode.DM;

İpuçları

  • Required özelliğini kullanarak en az bir belge eklenmesini kod yazmadan zorunlu kılabilirsiniz.
  • Uzantı, boyut ve adet kısıtlamalarını Categories içindeki AllowedFileExtensions, MaxFileSize, MaxFilesCount, MinFilesCount ile tanımlayın; BeforeFileAdd iptal edilemediği için kısıtlama doğru yer burasıdır.
  • Yalnızca BeforeFileRemove iptal edilebilir (RelatedDocumentsRemoveEventArgs.Cancel); belirli dosyaların silinmesini bu olayda engelleyin.
  • Yüklenen belgelerde metin araması yapacaksanız EnabledOCR özelliğini açın; OCR çıktısına RelatedDocumentFile.OCRData üzerinden ulaşılır.
  • ReadOnly ile formu salt okunur gösterdiğinizde mevcut belgeler görünür ama yeni dosya eklenemez veya silinemez.
  • Async metotları (AddFileByUpload, RemoveFile, DownloadFile vb.) sunucu kodunda .Result ile bekletmeyi unutmayın; aksi halde işlem tamamlanmadan devam edersiniz.
Tüm tasarımcı özellikleri ve üyeler (tam liste)

General: Name

Behavior: AddingMode, AddNewEnabled, AdvancedEdit, Categories, CreateEnabled, DeleteEnabled, EnabledOCR, FileDescriptionIsRequired, Files, Path, ReadOnly, Required, ShowCategoryDescription, ShowContentForImageFiles, ShowCreateDate, ShowCreator, ShowFileDescription, ShowFileExtension, ShowPath, Viewable, ViewType, Indexable

Appearance: Visible, Client Visible, Enabled, Client Enabled, Title, Caption, Style, Container Style, Custom Class Name, Control Id, Loading, Default Enabled, Default Client Enabled, Default Read Only, Entity Path, Target Id, Target Secret Key, Context Menu Key, Context Menu Column Key, Context Menu Target

Olaylar (Server): BeforeFileAdd, AfterFileAdd, BeforeFileRemove, AfterFileRemove, ValidatingEvent

Metotlar: AddFile, AddFileById, AddFileByUpload, AddFilesByUpload, UploadFile, UploadFiles, RemoveFile, RemoveFiles, RemoveAllFiles, DownloadFile, DownloadFiles, GetObjects, GetObjectsWithSecretKey, SetPath, ApplyChanges, GetData, GetValueAsObject

Enum'lar: RelatedDocumentsAddingMode (Local, DM, All); RelatedDocumentsViewType (Card, List, Compact, Button)