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
| Özellik | Açıklama |
|---|---|
Name | Nesnenin koddaki adı (ör. RelatedDocuments1). Koddan bu adla erişirsiniz. |
Behavior
| Özellik | Açıklama |
|---|---|
AddingMode | Belge ekleme biçimini belirler. Enum RelatedDocumentsAddingMode: Local (bilgisayardan yükleme), DM (Doküman Yönetimi'nden seçme), All (ikisi de). |
AddNewEnabled | Yeni dosya ekleme düğmesini açar veya kapatır. |
AdvancedEdit | Gelişmiş düzenleme seçeneklerini etkinleştirir. |
Categories | Belgelerin atanabileceği kategorilerin listesi (List<RelatedDocumentCategory>). |
CreateEnabled | Yeni belge oluşturmaya izin verir. |
DeleteEnabled | Eklenen belgenin silinebilmesini sağlar. |
EnabledOCR | Yüklenen belgelerde OCR (metin tanıma) işlemini açar. |
FileDescriptionIsRequired | Dosya açıklamasını zorunlu yapar. |
Path | Belgelerin kaydedileceği DM klasör yolu. |
ReadOnly | Nesneyi salt okunur yapar; yeni dosya eklenemez, silinemez. |
Required | En az bir belge eklenmesini zorunlu kılar; boşsa form kaydedilmez. |
ShowCategoryDescription | Kategori açıklamasını gösterir. |
ShowContentForImageFiles | Resim dosyalarının önizlemesini gösterir. |
ShowCreateDate | Belgenin oluşturulma tarihini sütun olarak gösterir. |
ShowCreator | Belgeyi ekleyen kullanıcıyı gösterir. |
ShowFileDescription | Dosya açıklaması sütununu gösterir. |
ShowFileExtension | Dosya uzantısını gösterir. |
ShowPath | Dosyanın saklandığı yolu gösterir. |
Viewable | Belgelerin görüntülenebilmesini sağlar. |
ViewType | Listenin görünüm biçimi. Enum RelatedDocumentsViewType: Card, List, Compact, Button. |
Indexable | Nesnenin içeriğinin indekslenip indekslenmeyeceği. |
Appearance
| Özellik | Açıklama |
|---|---|
Visible / Client Visible | Nesnenin görünürlüğü. |
Enabled / Client Enabled | Nesnenin aktif olup olmadığı. |
Title | Nesnenin başlığı (MultiLanguageText, çok dilli olabilir). |
Caption | Etiket bilgisi (ControlCaption). |
Style / Container Style | Nesnenin ve kapsayıcısının stili. |
Custom Class Name | Özel CSS sınıf adı. |
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: BeforeFileAdd → AfterFileAdd, dosya silerken BeforeFileRemove → AfterFileRemove
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.
| Olay | Argüman tipi | Ne zaman çalışır |
|---|---|---|
BeforeFileAdd | RelatedDocumentsAddEventArgs | Bir veya daha fazla dosya eklenmeden hemen önce. İptal edilemez. |
AfterFileAdd | RelatedDocumentsAddEventArgs | Dosya(lar) eklendikten hemen sonra. En sık kullanılan olaydır. |
BeforeFileRemove | RelatedDocumentsRemoveEventArgs | Bir dosya silinmeden hemen önce. e.Cancel = true ile iptal edilebilir. |
AfterFileRemove | RelatedDocumentsRemoveEventArgs | Dosya silindikten hemen sonra. |
ValidatingEvent | ValidatingEventArgs | Nesne doğrulanırken (salt okunur olay; += ile bağlanır). |
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) veResponseParameters.Cancelözelliği yoktur, dolayısıylaBeforeFileAddile ekleme engellenemez.RelatedDocumentsRemoveEventArgs(BeforeFileRemove/AfterFileRemove):Boolean Cancel,RelatedDocumentFile File(silinen tek dosya) veResponseParameters. Yalnızca buradaCancelvardır;BeforeFileRemoveiçindee.Cancel = trueyaparak 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ı):
| Üye | Tip | Açıklama |
|---|---|---|
Id | String | DM nesne kimliği (metin olarak). |
Name | String | Dosya adı. |
Description | String | Dosya açıklaması. |
Extension | String | Uzantı (ör. "pdf"). |
FileSize | Int64 | Bayt cinsinden boyut. |
Path | String | Dosyanın DM yolu. |
SecretKey | String | DM gizli anahtarı (indirme URL'si için). |
DownloadUrl | String | İndirme yolu. |
Data | Byte[] | Dosya içeriği (bayt dizisi). |
Category | RelatedDocumentCategory | Dosyanın atandığı kategori. |
CreateDate | Nullable<DateTimeOffset> | Oluşturulma tarihi. |
Creator / CreatorId | String / Int64 | Ekleyen kullanıcı. |
OCRData | String | OCR çıktısı (EnabledOCR açıksa). |
RelatedDocumentCategory (Categories ve RelatedDocumentFile.Category):
| Üye | Tip | Açıklama |
|---|---|---|
Id | Int64 | Kategori kimliği. |
CategoryId | String | Kategorinin GUID metni. |
Name / Description | Dictionary<String,String> | Dil → metin sözlüğü. |
AllowedFileExtensions | List<String> | İzin verilen uzantılar (boş liste = her tür). |
MaxFilesCount | Nullable<Int32> | En fazla dosya (null = sınırsız). |
MaxFileSize | Nullable<Int64> | En büyük boyut (null = sınırsız). |
MinFilesCount | Int32 | En az dosya sayısı. |
Path | String | Kategorinin 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 | İmza | Açıklama |
|---|---|---|
AddFile | Boolean AddFile(RelatedDocumentFile file) | Hazır oluşturulmuş bir dosyayı Files'a ekler (senkron). |
AddFileById | Task<Boolean> AddFileById(String categoryId, Int64 fileId) | Var olan bir DM dosyasını kimliğiyle bir kategoriye ekler. |
AddFileByUpload | Task<Boolean> AddFileByUpload(String categoryId, RDUploadFile file) | Yeni baytları yükleyerek ekler. |
AddFilesByUpload | Task<Boolean> AddFilesByUpload(String categoryId, List<RDUploadFile> files) | Birden çok dosyayı tek seferde yükler. |
UploadFile | Task<RDUploadedFile> UploadFile(String path, RDUploadFile file) | Belirtilen yola bir dosya yükler. |
UploadFiles | Task<List<RDUploadedFile>> UploadFiles(String categoryId, List<RDUploadFile> files) | Bir kategoriye çoklu yükleme. |
RemoveFile | Task<Boolean> RemoveFile(Int64 fileId) / RemoveFile(RelatedDocumentFile file) | Tek dosyayı siler. |
RemoveFiles | Task<Boolean> RemoveFiles(List<RelatedDocumentFile> files) / RemoveFiles(List<Int64> files) | Çok dosyayı siler. |
RemoveAllFiles | Task<Boolean> RemoveAllFiles() | Tüm dosyaları temizler. |
DownloadFile | Task<RDDownloadedFile> DownloadFile(Int64 fileId) / DownloadFile(RelatedDocumentFile file) | Dosya içeriğini bayt olarak indirir. |
DownloadFiles | Task<List<RDDownloadedFile>> DownloadFiles(...) | Çok dosyayı indirir. |
GetObjects | List<RelatedDocumentObject> GetObjects(List<Int64> objectIds, FormHttpParameters p) | Dosya meta verilerini döner (içerik yok). |
GetObjectsWithSecretKey | List<RelatedDocumentObject> GetObjectsWithSecretKey(List<ObjectSecret> objectSecrets, FormHttpParameters p) | Gizli anahtarla meta veri okur. |
SetPath | Void SetPath(String path) | Nesnenin yazacağı DM yolunu ayarlar. |
ApplyChanges | Void 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");
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);
}
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ı
CategoriesiçindekiAllowedFileExtensions,MaxFileSize,MaxFilesCount,MinFilesCountile tanımlayın;BeforeFileAddiptal edilemediği için kısıtlama doğru yer burasıdır. - Yalnızca
BeforeFileRemoveiptal 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ınaRelatedDocumentFile.OCRDataüzerinden ulaşılır. ReadOnlyile formu salt okunur gösterdiğinizde mevcut belgeler görünür ama yeni dosya eklenemez veya silinemez.- Async metotları (
AddFileByUpload,RemoveFile,DownloadFilevb.) sunucu kodunda.Resultile 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)