FileSelector

Kullanıcının forma dosya yükleyip seçebileceği nesnedir. Sözleşme, fatura, görsel ya da herhangi bir belgeyi forma eklemek için kullanılır.

Bu nesnenin tek bir değeri (Value) yoktur. Seçilen dosyalar Files listesinde (List<FileSelectorItem>) tutulur. Bir FileSelectorItem yalnızca kimlik bilgisi taşır: Id, Name, Path, SecretKey. Dosyanın baytları ya da kategorisi bu nesnede yer almaz; içeriği indirmek için DownloadFile metodunu kullanırsınız.

Sınıf zinciri FileSelector : CompositeDataBoundControl : DataBoundControl : VisualControl : BaseControl şeklindedir. Metin/değer girişi yapılan EditControl ailesinden türemediği için bu nesnede Value, Text, Placeholder, TextAlign gibi giriş özellikleri ve ValueChanged / TextChanged gibi olaylar yoktur.

Ne zaman kullanılır?

Forma bir veya birden çok dosya eklenmesi gereken her yerde kullanılır: teklif dosyası, kimlik fotokopisi, imzalı sözleşme, ürün görseli. Tek bir dosya yeterliyse AllowSelectMultiple kapalı bırakılır; birden çok dosya gerekiyorsa açılır ve MaxSelectionCount ile sınır konur. İzin verilen uzantıları kısıtlamak için AllowedFileExtensions listesini kullanın; böylece doğrulamayı tek tek kod yazmadan tasarımcıdan halledersiniz.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. FileSelector1). Koddan bu adla erişirsiniz.
Field Name	Veritabanındaki alanın adı.
Caption	Nesnenin yanındaki etiket (ControlCaption, çok dilli olabilir).

Behavior

Özellik	Açıklama
AllowedFileExtensions	İzin verilen dosya uzantıları listesi (List<String>, ör. pdf, docx, png). Boşsa tüm uzantılara izin verilir.
AllowRemove	Yüklenen dosyanın kaldırılmasına izin verir.
AllowSelectMultiple	Birden çok dosya seçilmesine izin verir. Kapalıysa tek dosya seçilir.
AllowView	Yüklenen dosyanın önizlenip görüntülenmesine izin verir.
Files	Seçilen dosyaların ayrıntılı listesi (List<FileSelectorItem>). Her öğe Id, Name, Path, SecretKey taşır.
MaxSelectionCount	En fazla kaç dosya seçilebileceğini sınırlar (Int32).
ReadOnly	Nesneyi salt okunur yapar; yeni dosya eklenemez.
Required	Alanı zorunlu yapar; dosya seçilmeden form kaydedilmez.
Indexable	İçeriğin tam metin aramada indekslenip indekslenmeyeceğini belirler.
SelectionTargetId	Mevcut belgeden seçimde hedef klasörün kimliği.
SelectionTargetPath	Mevcut belgeden seçimde hedef klasörün yolu.
UploadTargetId	Yüklenen dosyanın kaydedileceği hedef klasörün kimliği.
UploadTargetPath	Yüklenen dosyanın kaydedileceği hedef klasörün yolu.
UploadTargetSecretKey	Yükleme hedefi için gizli anahtar.

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).
Style / Container Style	Nesnenin ve kapsayıcısının görsel stili.
Custom Class Name	Nesneye verilecek özel CSS sınıf adı.
Loading	Nesnenin yükleniyor durumunu gösterir. ShowLoading() / HideLoading() ile yönetilir.

Context Menu

Özellik	Açıklama
Context Menu Key	Nesneye bağlanacak ContextMenu nesnesinin anahtarı.
Context Menu Column Key / Context Menu Target	Bağlam menüsünün hangi hedefe (Container / None / Row / Column) açılacağını belirler.

Olaylar

FileSelector'ın tasarımcıdan bağlanan kendi olayları yalnızca dosya ekleme ve kaldırma etrafında döner. Bu nesne bir EditControl türevi olmadığı için OnValueChanging / OnValueChanged / OnTextChanging / OnTextChanged gibi giriş olayları bu nesnede yoktur ve hiçbiri tetiklenmez.

OnInit / OnLoad / OnPreRender / OnRender ise BaseControl'tan miras alınan çerçeve yaşam döngüsü kancalarıdır; her nesne gibi bu nesnede de bulunurlar. Ancak bunlar nesnenin tasarımcıdan bağlanan kendi olayları değildir; aşağıda listelenen gerçek olaylar dosya ekleme/kaldırma olaylarıdır.

Gerçek olay yüzeyi yalnızca şunlardır: BeforeFileAdd, AfterFileAdd, BeforeFileRemove, AfterFileRemove ve doğrulama için salt okunur ValidatingEvent.

Kullanıcı dosya eklerken: BeforeFileAdd → AfterFileAdd Kullanıcı dosya kaldırırken: BeforeFileRemove → AfterFileRemove

Sunucu olayları (Server)

Olay	Sunucu giriş metodu	Olay argümanı	Ne zaman çalışır
BeforeFileAdd	OnBeforeFileAdd	FileSelectorAddEventArgs	Dosya eklenmeden hemen önce.
AfterFileAdd	OnAfterFileAdd	FileSelectorAddEventArgs	Dosya eklendikten hemen sonra.
BeforeFileRemove	OnBeforeFileRemove	FileSelectorRemoveEventArgs	Dosya kaldırılmadan hemen önce.
AfterFileRemove	OnAfterFileRemove	FileSelectorRemoveEventArgs	Dosya kaldırıldıktan hemen sonra.
ValidatingEvent	— (salt okunur)	ValidatingEventArgs	Form doğrulanırken nesnenin geçerliliği denetlenirken.

Olay argümanları: ne yük taşır ne de iptal eder

Benzer adlarına rağmen bu olaylar boş taşıyıcılardır. Hem FileSelectorAddEventArgs hem de FileSelectorRemoveEventArgs yalnızca BaseEventArgs'tan gelen ResponseParameters özelliğini taşır. Bunun iki önemli sonucu vardır:

• Olay argümanında eklenen/kaldırılan dosyanın bilgisi yoktur (FileName, File, Files gibi bir alan bulunmaz). Hangi dosyanın değiştiğini öğrenmek için olay sonrasında Files listesini yeniden okuyun.
• Cancel özelliği yoktur; bu nedenle BeforeFileAdd / BeforeFileRemove sunucu tarafında iptal edilemez. Uzantı kısıtlaması için kod yazmak yerine tasarımcıdaki AllowedFileExtensions özelliğini kullanın.

(Karşılaştırma: yalnızca RelatedDocuments nesnesinin BeforeFileRemove olayı RelatedDocumentsRemoveEventArgs.Cancel ile iptal edilebilir; FileSelector'da böyle bir yetenek yoktur.)

Metotlar

FileSelector'ın gücü kodla dosya ekleme, kaldırma, indirme ve yükleme metotlarındadır. Çoğu metot Task<...> döndürür (asenkrondur); akış/sunucu kodunda .Result ya da await ile sonucu alabilirsiniz.

Metot	Döndürür	Açıklama
AddFileById(long fileId)	Task<Boolean>	DM'deki var olan bir dosyayı kimliğiyle ekler.
AddFileByUpload(FSUploadFile file)	Task<Boolean>	Tek bir dosyayı bayt içeriğiyle yükleyip ekler.
AddFilesByUpload(List<FSUploadFile> files)	Task<Boolean>	Birden çok dosyayı yükleyip ekler.
RemoveFile(long fileId)	Task<Boolean>	Kimliğiyle belirtilen dosyayı kaldırır.
RemoveFile(FileSelectorItem file)	Task<Boolean>	Verilen öğeyi kaldırır.
RemoveFiles(List<FileSelectorItem> files) / RemoveFiles(List<long> files)	Task<Boolean>	Birden çok dosyayı kaldırır.
RemoveAllFiles()	Task<Boolean>	Tüm dosyaları kaldırır.
DownloadFile(FileSelectorItem file) / DownloadFile(long fileId)	Task<FSDownloadedFile>	Dosyanın içeriğini (Data) ve meta verisini indirir.
DownloadFiles(List<FileSelectorItem> files) / DownloadFiles(List<long> files)	Task<List<FSDownloadedFile>>	Birden çok dosyayı indirir.
UploadFile(string path, FSUploadFile file)	Task<FSUploadedFile>	Bir dosyayı belirtilen yola yükler.
UploadFiles(List<FSUploadFile> files)	Task<List<FSUploadedFile>>	Birden çok dosyayı yükler.
GetObjects(List<long> objectIds, FormHttpParameters httpParameters)	List<FileSelectorObject>	Dosyaların zengin meta verisini (ad, açıklama, indirme bağlantısı) getirir.
GetValueAsObject()	Object	Nesnenin serileştirilmiş değerini nesne olarak verir.

Yardımcı tipler

FileSelectorItem (her Files öğesinin biçimi):

Üye	Tip	Açıklama
Id	String	Dosyanın kimliği.
Name	String	Dosyanın adı (uzantısıyla birlikte).
Path	String	Dosyanın yolu.
SecretKey	String	Dosyaya erişim için gizli anahtar.

FSUploadFile (yükleme için verdiğiniz nesne): Data (Byte[]), MimeType (String), Name (Dictionary<String,String>, dile göre), Description (Dictionary<String,String>).

FSDownloadedFile (indirmeden dönen nesne): Data (Byte[]), MimeType, DownloadUrl, FileId (Int64), SecretKey, Name ve Description (dile göre sözlük).

FSUploadedFile (yüklemeden dönen nesne): FileId (Int64), SecretKey, Name, Description.

FileSelectorObject (GetObjects / akış tarafı okuma sonucu): Id (Int64), Name ve Description (dile göre sözlük), Path, DownloadUrl, SecretKey, Type (Int32), Creator, CreatedAt (DateTimeOffset?).

Kod örnekleri

Bir FileSelector'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. Bu nesnenin tek bir değeri olmadığı için dosyalara Files üzerinden ulaşılır.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz:

// Seçilen dosya sayısını oku
int dosyaSayisi = FileSelector1.Files.Count;

// Dosyaları dolaş, ad ve yol bilgisini al
foreach (FileSelectorItem dosya in FileSelector1.Files)
{
    string ad = dosya.Name;
    string yol = dosya.Path;
}

// Dosya seçilip seçilmediğini kontrol et
bool dosyaVar = FileSelector1.Files.Count > 0;

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz:

// Seçilen dosya sayısını oku
var nesne = (Bimser.CSP.FormControls.Controls.FileSelector)Document1.Controls["FileSelector1"];
int dosyaSayisi = nesne.Files.Count;

// İlk dosyanın adını al
if (nesne.Files.Count > 0)
{
    string ilkDosyaAdi = nesne.Files[0].Name;
}

not

Document1.Controls indeksleyicisi taban tipi döndürür

Document1.Controls["FileSelector1"] genel bir Control döndürür. Files, AddFileByUpload gibi FileSelector'a özgü üyelere erişmek için yukarıdaki gibi FileSelector tipine cast edin. Alternatif olarak akış tarafında dosyaların meta verisini doğrudan form.GetFileSelectorObjects(...) ile de okuyabilirsiniz (aşağıdaki son örnek).

İstemci kodu (TypeScript, tarayıcı)

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

// Seçilen dosya sayısını oku
const dosyaSayisi = this.FileSelector1.files.length;

// Dosya seçilip seçilmediğini kontrol et
const dosyaVar = this.FileSelector1.files.length > 0;

Örnek 1: Yüklenmiş dosyaları dolaşıp adlarını okuma

Forma eklenen dosyaların adlarını okuyup başka bir alanda göstermek için Files listesini dolaşın. Olay argümanı dosya bilgisi taşımadığından, AfterFileAdd sonrasında doğru yer burasıdır.

void FileSelector1_AfterFileAdd(object sender, FileSelectorAddEventArgs e)
{
    // Olay argümanı dosya taşımaz; güncel listeyi yeniden okuyoruz.
    var adlar = new List<string>();
    foreach (FileSelectorItem dosya in FileSelector1.Files)
    {
        adlar.Add(dosya.Name);
    }

    TextArea1.Value = string.Join(", ", adlar);
    TextArea1.Text  = TextArea1.Value.ToString();
}

Örnek 2: Koddan var olan bir dosyayı kimliğiyle ekleme

DM'de zaten bulunan bir dosyayı (ör. bir şablon ya da başka bir akıştan üretilmiş çıktı) forma kimliğiyle ekleyin. AddFileById asenkrondur; sonucunu .Result ile bekleyebilirsiniz.

long sablonDosyaId = 1024578;

// DM'deki şablon dosyayı FileSelector'a ekle
bool eklendi = FileSelector1.AddFileById(sablonDosyaId).Result;

if (!eklendi)
{
    ShowMessage("Uyarı", "Şablon dosya eklenemedi.",
        Bimser.CSP.FormControls.RuleManager.AlertType.Warning);
}

Örnek 3: Bayt içeriğiyle dosya yükleyip ekleme (AddFileByUpload)

Koddan ürettiğiniz (ör. bir PDF rapor) baytları doğrudan forma ekleyin. Yükleme nesnesi FSUploadFile'tır; adı ve açıklaması dile göre sözlük olarak verilir.

byte[] pdfBaytlari = RaporUret();   // kendi üretici metodunuz

var yuklenecek = new Bimser.CSP.FormControls.Models.FSUploadFile
{
    Data = pdfBaytlari,
    MimeType = "application/pdf",
    Name = new Dictionary<string, string> { { "tr-TR", "Talep_Ozeti.pdf" } },
    Description = new Dictionary<string, string> { { "tr-TR", "Otomatik üretilen talep özeti" } }
};

bool sonuc = FileSelector1.AddFileByUpload(yuklenecek).Result;

Örnek 4: Belirli bir dosyayı ya da tümünü kaldırma

AllowRemove ile kullanıcı arabirimden kaldırmaya izin verirken, koddan da RemoveFile / RemoveAllFiles ile temizleyebilirsiniz. Aşağıda adı eski ile başlayan dosyalar kaldırılır.

// Belirli dosyaları kaldır
foreach (FileSelectorItem dosya in FileSelector1.Files.ToList())
{
    if (dosya.Name.StartsWith("eski", StringComparison.OrdinalIgnoreCase))
    {
        FileSelector1.RemoveFile(dosya).Wait();
    }
}

// Ya da hepsini birden temizle
// FileSelector1.RemoveAllFiles().Wait();

Örnek 5: Dosya içeriğini indirme (DownloadFile)

DownloadFile dosyanın baytlarını FSDownloadedFile.Data içinde getirir. İndirilen baytları başka bir servise göndermek ya da işlemek için kullanabilirsiniz.

if (FileSelector1.Files.Count > 0)
{
    FileSelectorItem ilk = FileSelector1.Files[0];

    Bimser.CSP.FormControls.Models.FSDownloadedFile indirilen =
        FileSelector1.DownloadFile(ilk).Result;

    byte[] icerik = indirilen.Data;
    string tip = indirilen.MimeType;
    // icerik baytlarıyla işlem yapın (ör. arşive yazın, dış servise gönderin)
}

Örnek 6: Akış kodundan dosya meta verisini okuma (GetFileSelectorObjects)

Akış kodunda elinizde FormInstance (örn. form) varsa, FileSelector'a eklenmiş dosyaların zengin meta verisini doğrudan okuyabilirsiniz. Bu, indirme bağlantısı (DownloadUrl) ya da dile göre ad gibi bilgilere erişmenin doğrulanmış yoludur.

// FileSelector'daki dosyaların kimliklerini topla
var kimlikler = new List<long>();
var fs = (Bimser.CSP.FormControls.Controls.FileSelector)Document1.Controls["FileSelector1"];
foreach (FileSelectorItem dosya in fs.Files)
{
    kimlikler.Add(long.Parse(dosya.Id));
}

// Zengin meta veriyi getir
List<Bimser.CSP.FormControls.Models.FileSelectorObject> nesneler =
    form.GetFileSelectorObjects(kimlikler).Result;

foreach (var n in nesneler)
{
    string ad = n.Name.ContainsKey("tr-TR") ? n.Name["tr-TR"] : null;  // dile göre ad
    string indirmeBaglantisi = n.DownloadUrl;
}

İpuçları

• Belirli uzantılarla sınırlamak için tasarımcıdaki AllowedFileExtensions listesini kullanın; olay argümanı dosya taşımadığı ve iptal desteklemediği için uzantı kontrolünü koddan yapamazsınız.
• Tek bir dosya yeterliyse AllowSelectMultiple kapalı kalsın; birden çok dosyada MaxSelectionCount ile üst sınır koyun.
• Dosya zorunluysa Required özelliğini açın; kullanıcı dosya seçmeden formu kaydedemez.
• Yüklenen dosyanın saklanacağı yeri UploadTargetPath / UploadTargetId ile belirleyin.
• Metotların çoğu Task<...> döndürür (asenkrondur); akış kodunda sonucu .Result / .Wait() ile bekleyin.
• Before/AfterFileAdd ve Before/AfterFileRemove argümanları hangi dosyanın değiştiğini söylemez; değişen dosyayı öğrenmek için olay içinde Files listesini yeniden okuyun.

Tüm tasarımcı özellikleri (tam liste)

General: Name, Field Name, Caption

Behavior: AllowedFileExtensions, AllowRemove, AllowSelectMultiple, AllowView, Files, MaxSelectionCount, ReadOnly, Required, Indexable, SelectionTargetId, SelectionTargetPath, UploadTargetId, UploadTargetPath, UploadTargetSecretKey, EntityPath

Appearance: Visible, Client Visible, Enabled, Client Enabled, Default Enabled, Default Client Enabled, Default ReadOnly, Title, Style, Container Style, Custom Class Name, Loading, Control Id

Context Menu: Context Menu Key, Context Menu Column Key, Context Menu Target

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

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