yeoman Arşiv

SharePoint Framework (SPFx) Visual Studio Extension

Şimdiye kadar benim bahsettiğim ve şüphesiz farklı kaynaklardan ulaştığınız pek çok SharePoint Framework örneğinde az alınan editör Visual Studio Code oldu. Bunun aslında temel nedeni Microsoft’un da bu konuda en ideal editör olarak Visual Studio Code’u gösteriyor olması. Ancak eminim pek çoğunuz geliştirmelerinizde Visual Studio’nun farklı sürümleri üzerinde çalışıyorsunuz ve alışkanlıklarınızdan vazgeçmek istemiyorsunuz. Bu noktada SPFx projelerinizi Visual Studio ortamında nasıl geliştireceğinizden bahsetmekte yarar görüyorum.

Öncelikle belirtmek gerekir ki bu konuda bir extension yayınlanmış durumda 🙂 Ek olarak söylemekte fayda var, henüz bu extension ile sahip olabileceğiniz tek proje şablonu webpart projesi şeklinde. Dolayısıyla bu veya çıkacak farklı extensionları takip etmekte yarar var. Sonraki süreçte Visual Studio’nun da oyunda tam destek ile yerini alacağından şüphemiz yok.

Extension GitHub üzerinden yayınlanmış durumda ve açık kaynak kodlu. İncelemek isterseniz kod bloklarından ilerleyebilmek ile beraber hızlıca konuya başlamak isteyenler için şimdiye kadar yayınlanmış beş tane release versiyonu da bulunuyor. Kaynaklara ulaşmak için aşağıdaki adresleri kullanabilirsiniz.

Release versiyonu indirdiğinizde sizi bir vsix dosyası karşılayacak. Çift tıklayarak kurulum sürecini başlatabilirsiniz. Tabi bu işlem esnasında Visual Studio’nuzun kapalı kalması gerekiyor.

 

 

Şablonun yüklenmesini takiben Visual Studio’yu açtığınızda ise aşağıdaki şekilde proje şablonunuza ulaşabilecek ve geliştirmenizi yapabileceksiniz.

 

 

Sonrasında Visual Studio’yu başlatıp File > New > Project şeklinde alıştığınız proje oluşturma yolunu takip ettiğinizde şablonun başarıyla yüklendiğini ve karşınıza geldiğini göreceksiniz.

 

 

Hatırlarsanız proje şablonumuzu Yeoman ile oluşturduğumuzda bize bazı sorular ile geliyordu. Webpartın adı ne olsun, hangi js frameworkünü kullanacaksın, vb. Visual Studio şablonu da benzer şekilde bir form aracılığı ile bunu soracaktır. Gerekli bilgileri doldurup “generate” butonunu tıklayarak projenizin oluşmasını sağlayabilirsiniz.

 

 

Dilerseniz bu işlemi yine Yeoman kullanarak da yapabilirsiniz, aşağıdaki şekilde.

 

SPFx Merhaba Dünya

Bir önceki kısa bilgilendirme yazısıyla kısaca SPFx Nedir? sorusuna yanıt vermeye çalışmıştım. Yazıya buradan erişebilirsiniz. Şimdiyse ortam kurulumumuzu yapıp bir webpart geliştirerek devam etmek istiyorum. Yazının sonunda aslında aynı örneğin yapılmış olduğu MSDN Tutorial’ına ait videoyuda bulabilirsiniz.

SharePoint FrameWork ile çalışmak için ihtiyacımız olan bileşenler;

  • Yeoman
  • Gulp
  • Node.js
  • Visual Studio Code

Öncelikle Node.js’i indirerek başlayabiliriz. Node.js’i kendi sitesinden stabil versiyonunu indirerek temin edebilir ve herhangi bir özel ayar yapmaksızın kurulum dosyasını çalıştırabilirsiniz. Node.js sitesine buradan erişebilirsiniz.

Bundan sonraki bölümde biraz command prompt üzerinde olacak çalışmalarımız. Atlamamanız gereken nokta command promptu “Run as Administrator” modunda açmak olmalı. İlk etapta Gulp aracını kurarak başlıyoruz. Gulp paketleme ve bundle etme olarak tabir edebileceğimiz işlemleri gerçekleştiriyor olacak. Sadece SharePoint Framework’e (SPFx) özel bir araç veya kavram değil elbette. Yanlış hatırlamıyorsam Visual Studio’ya ilk olarak .Net Core proje yapısıyla beraber doğrudan entegre edilmişti. Bu işlem internet bağlantınıza bağlı olarak yaklaşık 1-2 dakika kadar sürecektir.

Sonra SharePoint Framework için gerekli dosyaların kurulumunu yapmamız gerekiyor. Bu işlem bir müddet daha uzun sürüyor diğerlerine göre zira bir hayli dosyanın download edilmesi gerekiyor. Ben geliştirme ortamı olarak Azure üzerinde bulunan bir sanal makineyi kullanıyorum. Bu nedenle internet bağlantısında maalesef ülke olarak lokalde sahip olduğumuz bağlantı hızına göre bir miktar daha avantajlı olabiliyorum indirme sürelerinde. Lokal bağlantıda yaptığım denemelerde yaklaşık 20-25 dk sürmüştü bu işlem, Azure üzerinde 4-5 dakikada tamamlandı.

Bu bölümde önemli bir parametre olarak -g parametresine dikkatinizi çekmek istiyorum. Bu parametre ile aslında sonraki işlemlerimiz için de bir altyapı hazırlamış oluyor, global olarak gerçekleştirmiş oluyoruz işlemi.

Bundan sonraki aşamamız sadece geliştirme aracımızın kurulumunu yapmak. Ben Visual Studio Code’u tercih edeceğim ama kurulu durumda Visual Studio’nuz veya bir önceki yazıda bahsettiğim araçlarınız varsa onlar ile de ilerleyebilirsiniz, neticede ihtiyacımız bir kod editörü. Visual Studio Code’u buradan temin edebilirsiniz.

Şimdi artık webpartımızı oluşturabiliriz. Bunun için de bir komuttan yararlanacağız, bu bize aslında temel amacımız olan merhaba dünya webpartının bir örneğini oluşturacak. Amacımız bunun üzerinde değişiklikler yaparak yayına alabilmek.

Bu bölümde komut satırı ilk oluşturacağınız webparta ilişkin bazı sorular ile sizi yönlendiriyor olacak. Webpartınızın adı ne olsun, hangi javascript frameworkünü kullanacaksınız, solution folderı nerede olsun, webpartınızın açıklamasında ne yazsın, vb. Bu bilgileri verdikten sonra gerekli bileşenler internetten indirilecek ve webpartınız hazır hale gelecek.

Ekranda da yazdığı gibi aslında “gulp serve” komutunu çalıştırarak webpartınızın local Workbench üzerinde çalışmasını sağlayabilirsiniz ancak burada araya girerek yine bir önceki kısa yazımda bahsettiğim known-issue’ya dönmek istiyorum. Özellikle geliştirme tarayıcısı olarak Chrome kullanıyorsanız sertifika nedeniyle sorun yaşamanız mümkün. Bu nedenle aşağıdaki komutuda ekleyip sonra gulp serve demeyi önereceğim.

Şimdi komutumuzu çalıştırarak paketleme işlemini ve ardından çalıştırmayı gerçekleştirebiliriz.

Ekrandaki ardışık otomatik komut setlerinden de göreceğiniz üzere öncelikle paketleme işlemi gerçekleştiriliyor. Bu esnada aslında full trust solutionlarda elde ettiğimiz wsp benzeri bir paketleme gerçekleşiyor. gulp serve debug veya release modda paketleme gerçekleştirebiliyor. Tamamlandığında komut satırınız debug modda ve kodunuza doğrudan bağlı olarak değişiklikleri takip eder modda açıkken bir taraftanda lokal workbench üzerinde uygulamanızı test edebilme imkanına sahip oluyorsunuz.

Workbench adresine dikkatinizi çekmek istiyorum bu aşamada. Malum SharePoint ile full trust geliştirmelerde SharePoint’in yüklü durumda olduğu bir geliştirme ortamını tercih etmek durumundayız. Çünkü pek çok bileşen SharePoint ile beraber yükleniyor geliştirme ortamımıza. Ancak SPFx ile çalışmada buna gerek yok. Doğrudan localhost üzerinde bir workbench ile SharePoint ortamındaymış gibi testlerinizi gerçekleştirebilirsiniz. Yukarıdaki ekranda gördüğünüz “HelloWorld” isimli  webpartı sayfaya eklememiz yeterli çıktıyı görmek adına.

Webpartın sol bölümünde yer alan edit butonu aracılığı ile webpart toolpane’inize ulaşmak mümkünken silme komutuylada webpartı sayfanızdan silebilirsiniz. Düzenleme moduna aldığımızda toolpane parametrelerini görüntüleyebilir ve düzenleyebiliriz. Bu hazır webpart şablonunda description alanı toolpane içinde yer alıyor. Denerken dikkatinizi çekmek istediğim nokta toolpane’de yaptığınız değişiklikler sayfayı kaydetmenizi gerek kalmadan runtimeda webpartınızın üzerine uygulanmaya başlıyor.

Bir önceki yazımda SPFx’in özelliklerinden bahsederken kontrollerin responsive olduğundan bahsetmiştim. Workbench bunu da test etmenize imkan veriyor. Tarayıcının sağ üst köşesinde göreceğiniz tablet, desktop ve telefon seçeneklerine tıklayarak sayfanızın nasıl tepki verdiğini gözlemlemeniz mümkün.

Kısa bir süreliğine komut satırına geri dönelim. Burada bazı kısa yollar ile kodunuza path olarak veya Visual Studio Code ile erişebilirsiniz. Mesela aşağıdaki komut ile kodlarınızın bulunduğu path’i otomatik olarak açmasını sağlayabilirsiniz.

Veya kodunuzu düzenleme modunda açmak için aşağıdaki kodu kullanabilirsiniz. Bu sayede projeniz Visual Studio Code içerisinde açılacaktır.

Visual Studio Code içerisinde sol bölümde gerekli konfigürasyon dosyalarının yanısıra “src” isimli bir klasör yapısı göreceksiniz. Bu bölüm webpart kodlarınızın yer aldığı bölümü işaret ediyor. Ben kodu açarak tutorial içerisindeki örnekte yer alan düzenlemeleri yapıp webpartımı yeniden çalıştırmak istiyorum. Burada dört tane daha toolpane parametresi eklemeye ve bundalardan bir tanesini de önyüzde göstermeye çalışacağım. ToolPane parametrelerinin tamamı IHelloWorldWebPartProps.ts dosyası içerisinde yer alıyor. Bu alana ikisi string, ikisi boolean tipte dört tane daha property ekliyorum aşağıdaki kod bloğu ile.

Bu şekilde sadece property tanımlamalarını yapmış olduk elbette. Bu propertylerin webpartımız ile ilişki içerisinde olabilmesi ve varsayılan değerlerini alabilmesi için HelloWorldWePart.ts dosyasını açıyor ve getPropertyPaneConfiguration() metodunu bularak içeriğini aşağıdaki şekilde değiştiriyorum.

Bu şekilde bir tane Multi-Line textbox, bir tane CheckBox, bir DropDown ve bir de Toogle eklemiş oluyorum değişkenlerime bağlı olarak. Kullanmadan önce son bir işim daha kaldı. Bu toolpane parametrelerinin paket ile beraber gönderilmesini sağlayabilmek amacıyla HelloWorldWebPart.manifest.json dosyasını açıp içerisinde yer alan “preconfiguredEntries” bölümüne tanımlamış olduğum her bir ToolPane değişkeni için varsayılan değerleri atıyorum. Bu bölüm ayrıca webpartınızın adını, açıklamasını, vb de değiştirebileceğiniz, aslında on-premise geliştirmede de karşımızda olan manifest dosyası.

Önyüzde görüntülenmesini de test etmek amacıyla HelloWorldWebPart.ts dosyamı yeniden açıp render() metodu içerisindeki html bölümde istediğim alana aşağıdaki şekilde ekleme yaparak kullanmam mümkün.

Hemen güzel bir noktadan bahsedelim. Eğer bir önceki gulp serve komutunuzdan sonra Ctrl + C komutunu gönderirseniz projeniz debug moddan çıkar ve workbench kapanır. Ancak diyelim ki yukarıda bahsettiğim kod değişikliklerini projeniz çalışır durumdayken yaptıysanız yeniden çalıştırmanıza gerek olmadan sadece kaydetmeniz yeterlidir. Zaten bu esnada komut satırını izleyecek olursanız, yaptığınız değişikliklerin çalışan projeye uygulanmaya başladığını gözlemleyebilir ve projenizi yeniden çalıştırmadan test etmeye devam edebilirsiniz. Eğer projenizi debug moddan çıkartmak istiyorsanız Ctrl + C komutunu yazarak ve karşınıza gelen onay ekranını “y” komutuyla geçerek projenizin çalışmasını durdurabilirsiniz.

Bizim yaptığımız değişikliklerden sonra kaydettiğimizde elde edeceğimiz görüntü aşağıdaki şekilde olacaktır.

Ve son bir noktadan bahsetmek istiyorum. Lokal ortamda çalışırken uygulamanızı local workbench ile çalıştırdınız. Peki ama SharePoint Online’da bu uygulama nasıl görünecekti. Bunun için geliştirme aşamasında herhangi bir deployment yapmadan silerseniz sadece aşağıdaki formatta SharePoint Online Workbench’inizi açabilir ve uygulamanızı bu ortamda da test edebilirsiniz.

https://[tenantName].sharepoint.com/sites/[siteName]/_layouts/15/workbench.aspx

Bu durumda da çıktınız değişmeyecektir. Aşağıdaki ekranda url satırına özel olarak dikkatinizi çekmek isterim SharePoint Online adresine gittiğinden emin olmak adına.

Örnek projenin kodlarına GitHub üzerinden ulaşabilirsiniz. Ve tutorial’ın video halinden devam etmek isteyenler için aşağıda bulabilirsiniz.