SharePoint Framework (SPFx) Feature Pack 2 ile beraber on-premise ortamları da destekler hale geldi. Neredeyse SharePoint online ile benzer bir seviyede SPFx çözümlerini artık on-premise ortam için de geliştirebiliyorsunuz. SPFx’in önemi aslında Microsoft’un SharePoint geliştirme noktasındaki hem en modern hem de hedefte stabil ve en yoğun kullanılan geliştirme modeli haline getirmesinden kaynaklanıyor. Dolayısıyla bir tercih olmanın ötesinde genel SharePoint geliştirme ortamı olarak düşünebiliriz bundan sonrası için.
Pek çok kişi artık SharePoint on-premise versiyonunun ortadan kalkacağına yönelik tahminlerde bulunurken Microsoft’un MS Ignite’da SharePoint 2019’u da diğer Office ürün ailesi ile beraber anmaya başlaması bu konudaki tahminleri boşa çıkarttı. Bu nedenle on-premise ortam için de genel SharePoint geliştirme yönteminin SPFx olacağı noktasında bir soru işareti kalmamış oluyor.
SPFx’in son haliyle getirdiği bazı yeniliklere bakacak olursak;
Tenant seviyesinde App Catalog’lar üzerinden yaygınlaştırılabiliyor olması nedeniyle kolay ve yönetilebilir bir yaygınlaştırma ortamı sunuyor.
Henüz developer previewde olan GraphHttpClient aracılığı ile Office Graph üzerinde user Access ve token işlemlerini en kolay yapabileceğiniz yapı olarak karşımıza çıkıyor. Normal bir webpart veya SharePoint geliştirmesinde Graph API üzerinden user token oluşturma işleminde arada login sayfası göstermeden ilerleyebilmek için bir hayli takla atılması gerekebiliyordu.
Her yazılım projesinde olduğu gibi SharePoint Framework üzerinde uygulama geliştirirken de ihtiyaç duyacağımız ana konulardan bir tanesi debug. Microsoft’un da belirttiği üzere SPFx projeleri geliştirmek için en ideal kod editörü olarak Visual Studio Code’u göstermek mümkün. Bu nedenle bende bu yazıda Visual Studio Code kullanarak SPFx projelerinizi nasıl debug edebileceğiniz üzerinde durmaya çalışacağım.
Debug işlemi için en ideal ve basit çözüm Google Chrome web tarayıcısı ile çalışmak. Bu nedenle öncelikle Google Chrome’u aşağıdaki adresten indirmenizi ve kurmanızı öneriyorum.
Sonrasında çalışacağımız editör olan Visual Studio Code içerisindeki extensions bölümünden Debugger for Chrome eklentisini indirmenizi ve kurmanız gerekecek. Bu işlem için Visual Studio Code içerisinde yer alan en sol menüdeki en altta yer alan Extensions (Ctrl + Shift + X) bölümünü tıklamanız ve “Debugger for Chrome” etiketini arayarak yüklemeniz gerekiyor.
Yükleme sonrası ekranında yönlendirmesi ile Visual Studio Code’u yeniden yüklemeniz gerekecek. Bunun için “Reload” butonunu kullanabilirsiniz.
Local Workbench Projenizin Debug Edilmesi
Visual Studio Code içerisinde sol bölümdeki “Debug” panelini aktive edin. Bu bölümde henüz bir debug konfigürasyonunuz olmadığından profil seçimi yapabileceğiniz kısmı boş olarak göreceksiniz.
Bu bölümde “No configuration” yazan kısmı tıklayarak Google Chrome için debug konfigürasyonu oluşturma yolunu seçin. Ardından oluşacak launch.json dosyasının içeriğini intellisense yardımıyla siz doldurabileceğiniz gibi local Workbench için aşağıdaki konfigürasyon bölümü ile değiştirebilirsinizde.
Dilerseniz aynı adımları tekrar uygulayarak local Workbench yerine hosted ortamdaki SharePoint platformunuz için de ayrı bir debug profili ekleyebilirsiniz. Bu durumda aşağıdaki örnekte geçen url parametresini kendi ortamınıza göre düzenlemeniz gerekecektir.
Local Workbench + Hosted Environment Debug Profile
Bu konfigürasyonlar sonrası debug işlemine başlamak için tek yapılması gereken launch.js içindeyken önce hosted veya local şeklinde debug ortamını seçmek ve ardından debug işlemini başlatmak. Yeni bir pencere içinde uygulamanız debug modda açılacak ve breakpointleriniz işleme alınacaktır.
SharePoint Server üzerinde servis uygulamalarının hepsini arayüz üzerinden yapılandırabiliyoruz. Ancak bazılarında özellikle veritabanı isimleri sonlarında Guid içerir şekilde yaratıldığından benim gibi bu konuda takıntılı olanlar için sıkıntı yaratabilir. Bilindiği üzere SharePoint için PowerShell ile neredeyse yapamayacağımız bir işlem yok. Geliştirme ortamı gibi tek sunuculuk yapılarda bu işlemi aşağıdaki gibi bir PowerShell komut dizisi ile tamamlayabilirsiniz. Ayrıca bir süre sonra üç server, beş server gibi gerçek ortam SharePoint farmları için olan versiyonlarını da paylaşmaya çalışacağım.
Yakın zamanda gelen bir soruya istinaden SharePoint Online üzerinde bir doküman kütüphanesinde bulunan Microsoft Excel tabanlı bir dosyanın içeriğinin okunmasına istinaden küçük bir çalışma yapmıştım. Gerçi sonrasında özellikle veri yazma noktasında karşılaştığımız sorunlar nedeniyle biz konuyu Microsoft Office Graph kullanarak çözümledik ancak ihtiyaç duyulabileceğini düşünerek bu örneği de buradan paylaşmak isterim.
Yukarıda da belirttiğim gibi senaryomuzda ana konu dokümanın SharePoint Online üzerinde bir doküman kitaplığında bulunuyor olması. Burada yer alan Microsoft Excel dokümanını istemci tarafına indirmeden, herhangi bir Microsoft Office kurulumunu da yapmadan okumak istiyoruz. Yani aşağıdaki gibi bir görüntümüz var.
Okumak istediğimiz alan olan B6 hücresini range örneği de yapabilmek açısından daha önce “TEST1RANGE” ismiyle adlandırmış durumdayım. İşlemde temel amacım örneklemek olduğundan basit bir console uygulaması ile devam etmek istiyorum.
Uygulama tarafında client side bağlantı sağlayacağımızdan aşağıdaki referansları projemize ekliyoruz.
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\15\ISAPI\Microsoft.SharePoint.Client.dll
Ayrıca örnek projeye GitHubüzerinden erişebilirsiniz.
Sonuç olarak belirtmek isterim ki SharePoint Online’da bu tip işlemler ve çok daha fazlası için önerim Microsoft Office Graph kullanmak. Özellikle Office geliştirmeleri konusunda takipte tutmanızda yarar gördüğüm bir blog ise Microsoft MVP’lerimizden Erdem Avni Selçuk ‘un kişisel sitesi olacak.
Hazırladığımız SPFx tabanlı webpart projesinin javascript, css, image gibi varlıklarını sunabilmek için farklı alternatiflerimiz bulunuyor.
SharePoint / SharePoint Online altında yer alan bir asset library
Azure Blob Storage
Kendi belirleyeceğiniz bir CDN yapısı (yerel sunucu, AWS, vb diğer bulut çözümleri)
SPFx webpart projeniz içerisinde yer alan write-manifest.json bu dosyaların hangi adres üzerinden alınması gerektiğini belirttiğimiz alan. Varsayılan olarak aşağıdaki değer ile karşımıza çıkacaktır.
Burada yer alan PATH TO CDN alanı yukarıda bahsettiğim seçeneklerden varlıklarınızı yüklemiş olduğunuz yolu parametre olarak alacak ve sonraki paketlemeden itibaren de bunu kullanmaya başlayacaktır. Ben bu kısa yazıda Azure CDN’i nasıl kullanabileceğimizi özetlemeye çalışacağım. Bunun için şüphesiz öncelikle bir Microsoft Azure hizmetinizin bulunması gerekiyor. Şirketinizin sağlayacağı MSDN ayrıcalıkları ile elde edebileceğiniz gibi ücretsiz olarak trial bir Azure üyeliği de başlayabilirsiniz.
İhtiyacımız olan bileşenler ve oluşturma sıramız aşağıdaki gibi olacak;
Tüm varlıklarımızı gruplamamıza yarayacak bir resource group
Storage account
Blob container
CDN profile
CDN endpoint
Azure Portal’a https://portal.azure.com adresinden ulaştıktan sonra sol menüden Resource groups > Add bağlantısını tıklayarak bir kaynak grubu oluşturabilirsiniz.
İsmin pek önemi yok ama kendinize ve beraber çalıştığınız ekibe göre bir isimlendirme formatıyla isimlendirmenizi öneririm. Resource grubunuz hazır olduğunda içerisine bir storage account ve blob container oluşturmamız gerekiyor. Çünkü varlık (asset) olarak adlandırdığımız javascript, css ve diğer dosyalarımızı bu yapı içine yükleyeceğiz. Bunun için oluşturduğunuz resource group ismini tıklayaray Add komutunu vermeniz ve Storage Account’u seçmeniz yeterli olacaktır.
Storage accountunuz oluştuğunda aşağıdaki gibi bir görüntü oluşacaktır.
Storage account ismini tıklayarak ulaşacağınız sayfa üzerinden “Blob” türünde bir container oluşturabilirsiniz.
Storage accountu oluşturduğumuz işlem adımlarıyla sırasıyla önce bir CDN Profile, ardından da CDN EndPoint yaratabilirsiniz. İlgili ekranlara ulaşmak için aşağıdaki gibi bir yolu izleyebilirsiniz.
Artık ihtiyacımız olan kaynakları yarattık ve projemizin içerisindeki ihtiyaç duyulan bilgileri girebilmek adına bazı notlar alalım. Önce neye ihtiyacımız olduğunu anlamaya çalışalım. Projemizin config klasörü altında deploy-azure-storage.json isminde bir dosyamız bulunuyor. Eğer Azure CDN kullanmak istiyorsak bu dosya içerisindeki bilgileri doldurmak durumundayız. Varsayılan hali aşağıdaki gibi ve sonraki kod bloğu ise benim düzenlediğim hali. Sizler de Azure işlemleriniz esnasında verdiğiniz bilgileri bu alana yerleştirebilirsiniz.
workingDir: Kodlarınızı bundle ettiğinizde javascript, css gibi yapılarınızın sıkıştırılmış hallerinin oluşturulduğu dizindir. Bu alanda bir değişiklik yapmıyoruz.
account: Microsoft Azure üzerinde oluşturduğunuz storage account için belirlediğiniz isim.
container: Storage account altında oluşturduğunuz blob container’ın ismi.
accessKey: Bu bölümden yukarıda bahsetmedim. Kısaca storage accountunuzu oluşturduğunuzda Azure Portal üzerinde sol bölümde göreceğiniz Access keys alanından alacağınız değer. Aşağıdaki gibi bir yoldan görüntüleyebilir ve kopyalayabilirsiniz.
Paketimizi oluşturmadan önce son bir işimiz kaldı. O da oluşturduğumuz CDN EndPoint adresini write-manifest.json içerisine yerleştirmek. Bunun için oluşturduğunuz CDN EndPoint adresini bulmamız gerekiyor. Daha öncekilere benzer bir şekilde resource group içerisinden endpoint adresini alabiliriz.
Bunun sonuna blob container adresimizi ekleyerek write-manifest.json dosyamızı da güncellememiz gerekiyor. Dosya içeriğimiz aşağıdaki gibi olacak.
Şimdi tüm dosyalarımızı kaydedip öncelikle varlıklarımızın Azure CDN’e kopyalanmasını sağlayabiliriz. Bunun için aşağıdaki komutu çalıştırmamız yeterli olacak.
1
gulp deploy-azure-storage
Bu komut sonrası dosyalarınız Azure Blob Storage’daki yerini alacaktır.
Azure Storage’daki durumu görmek için bir aracımız var aslında. Azure Storage Explorer isimli aracı indirerek kurduğunuzda aşağıdaki gibi bir görüntü ile dosyaların doğru yüklendiğini gözlemleyebilirsiniz.
Şimdi paketlememizi yapıp SharePoint’e güncellenmiş uygulama paketimizi yükleyebiliriz.
1
gulp package-solution--ship
Yeniden yükleme esnasında daha önceden yüklü bir paket olacağından güncelleme seçeneği çıkacaktır karşımıza ve bu ekranda artık kaynak dosyalarımızın Microsoft Azure CDN’den alınacağını da görmüş oluyoruz.
Şimdi sonucu görme zamanı, yine bir sayfa ekleyip webpartımızı bu sayfaya ekleyerek test edebiliriz. F12 ile developer console’unuda açıp varlıkların Azure CDN’den geldiğini doğrulamış olalım.
SPFx ile çok çok basit birkaç kod örneği ile bu altyapıyı kullanmak için nasıl bir altyapıya sahip olmanız gerektiğini SPFx Merhaba Dünya , yerel ortamda yaptıklarınızı nasıl test edebileceğinizi ise SPFx SharePoint Verileriyle Çalışmak ve SharePoint Workbench Nedir? kısa yazılarımda anlatmaya çalışmıştım. Şimdi ise hazırladığımız webpartı SharePoint Online üzerinde nasıl çalıştırabileceğimizden bahsetmek istiyorum. Burada bir yanlış anlaşılmanın önüne geçmek adına kısa bir açıklama yapmak isterim. Daha önceki örneklerde zaten SharePoint Online üzerinde webpartımızı test etmiştik. Bunu Workbench’in sağladığı avantajı kullanarak aslında ön izlemesini yaparak sağlamıştık. Burada üzerinde durmak istediğim konu ise uygulamamızı paketlemek ve bir paket olarak SharePoint Online App Catalog içerisine yüklemek.
Paketleme işlemini tamamen temiz bir şekilde sağlayabilmek için aşağıdaki adımları sırasıyla uygulamaya çalışacağım.
Öncelikle daha önce gulp serve komutuyla uygulamanızı local workbench’de çalıştırmış durumdaysanız Ctrl + C ile bu işlemi durdurun. Kaydedilmemiş dosyalarınız varsa kaydedin.
Daha önce paketleme yaptıysanız veya ortamı derleme esnasında oluşan dosyalardan temizleyerek başlamak istiyorsanız aşağıdaki şekilde temizlik işlemini yapabilirsiniz.
1
gulp clean
Projenizin config > write-manifest.json dosyasının içerisinde pakete ilişkin kaynakları yüklediğiniz bir alan olmalıdır. Bu bölüme herhangi bir değer girmezseniz bu yerel kaynakları kullanacağınız anlamına gelir. İsterseniz bu bölüme bir Azure CDN EndPoint’inin adresini veya SharePoint Online üzerindeki bir varlık kitaplığı adresini belirtebilirsiniz. Aslında sadece bu iki CDN yapısı ile sınırlı değiliz, farklı CDN yapıları da kullanabilirsiniz. Aşağıdaki ekranda örnek olarak bir SharePoint varlık kitaplığının kullanıldığını görebilirsiniz.
Not: Varsayılan olarak, eğer paketiniz ile beraber gidecek dosyalar için bir path bilgisi vermezseniz yaygınlaştırmasını yaptığınız paket her ne kadar SharePoint Online üzerinde de olsa, kullanacağı sıkıştırılmış javascript dosyaları ve diğer tüm kaynaklar yerel adreslerden gelecektir. Bu nedenle bu şekilde kaynak dosyalarının yerini belirtmediğiniz bir yaygınlaştırma sonrası eğer webpartınızı test etmek istiyorsanız gulp serve ile uygulamanızı localde de başlatmış olmalısınız.
Ardından aşağıdaki komut ile kodunuzun sıkıştırılmış halinin debug modda oluşturulmasını ve paketinizde kullanılacak dist klasöründe oluşturulmasını sağlayabilirsiniz.
1
gulp bundle--ship
Son olarak paketimizi oluşturmak için aşağıdaki komutu yazmamız yeterli olacaktır.
1
gulp package-solution--ship
Yukarıdaki ekran görüntüsünden de göreceğiniz üzere sharepoint\solution pathinde paket dosyalarımız oluşturuluyor. Kısaca bir göz atacak olursak proje dosya yapımız artık aşağıdaki hali almış oldu.
Burada paketleme anlamında bizim için en önemli klasörler temp ve sharepoint. temp klasörü içerisinde yukarıdaki bundle komutuyla paketlediğimiz sıkıştırılmış haldeki javascript dosyalarımızı ve kaynaklarımızı saklıyor. SharePoint Online veya Azure Blob Storage içerisinde saklamak istediğimizde dosyaları bu klasörden alabileceğiz / otomatik olarak atabilecek. SharePoint klasörü ise paketimizi içerisinde barındırıyor. Biraz daha detaylı bakalım ve içeriğinde neler var görelim.
Burada yer alan ve uzantısı .sppkg olan dosya paket dosyamız. App’larda .app, çözümlerde .wsp uzantısına alışmıştık genel kullanımda. Bunu da bir uzantı olarak hafızamıza almakta yarar var. debug klasörünün içerisinde ise paket içeriğimiz açık olarak duruyor.
Ayrıca isterseniz sppkg uzantısını zip yaparak da paket içerişinizi görebilirsiniz. Neticede çözüm paketleri aslında sıkıştırılmış dosya grupları sadece.
SharePoint Online’a yaygınlaştırmak ise son derece kolay. Öncelikle bir AppCatalog’unuz olmalı. Her tenantta en fazla bir tane yaratabiliyorsunuz zaten. App Catalog sitenizde “AppCatalog” isminde bir kütüphane yer alıyor. Bu, uygulama paketlerini yüklediğimiz ve bizi yönlendiren bir ekran. Bu kütüphane içerisine sppkg dosyasınızı sürükleyip bıraklamanız yeterli olacaktır.
İşlem sonrasında paketi deploy etmeden önce dikkatinizi çekmek istediği mesajların yer aldığı bir ekran ve deploy butonu görünecektir. Butonu tıklamanız durumunda bir sıkıntı olmadan uygulamanız yüklenecektir. Ben burada yine bir konuya dikkat çekmek istiyorum. Ekrandaki mesaş içerisinde ikinci paragraf bu istemci tabanlı çözümün aşağıda belirtilen adresten bazı içerikler alacağını belirtiyor. İşte burası yukarıda write-manifest.json’da düzenlediğimiz bir path farkındaysanız. Eğer write-manifest.json’da bir değer belirtmemiş olsaydık yerel kaynakları kullanmak üzere burada local Workbench’inizin adresi olan http://localhost:4321 yazıyor olacaktı. Yada bir başka örnek ile Azure CDN kullanmış olsaydık bu alanda Azure CDN EndPoint adresimiz yazıyor olacaktı.
Deneyebilmek için sitemin sağ üst köşesinde yer alan çark sembolüne tıklıyor ve “Add Page” komutunu veriyorum. Bu karşımıza Modern Layout kullanan bir sayfa getirecek. Sayfanın orta alanında ise Local Workbench’dekine benzer şekilde webpart seçimi yapabileceğiniz bir alanı.
Ve eklediğinizde webpartınız artık yerel herhangi bir kaynak kullanmaksızın SharePoint Online sayfanızdaki yerini almış olacak.
Son günlerde SPFx konusunda kendimce bilgi paylaşmaya çalıştığım yazılardan sonra sürekli test ekranlarını da gösterdiğim SharePoint Workbench’in ne olduğu hakkında biraz daha detay paylaşmak isterim.
SharePoint Workbench geliştiricilerin, geliştirdikleri webpartları SharePoint’e yaygınlaştırmalarına gerek kalmadan ön izlemelerine ve test etmelerine yardımcı olan bir geliştirici aracıdır.
SharePoint Workbench’in iki farklı formu bulunuyor;
Local Workbench: SharePoint Framework geliştirme araçları ile beraber yerel sunucu üzerine yüklenir.
SharePoint Online / On-Premise Workbench: SharePoint Online site koleksiyonu veya on-premise site koleksiyonu üzerinden erişilir. Bu durumda adres formatı https://your-sharepoint-site/_layouts/workbench.aspx şeklinde olacaktır.
Local Workbench hızlı ve herhangi bir yaygınlaştırma gerektirmeden hazırladığınız webpartları test etmenize imkan tanır. Bunu yaparken eksik kalacak tek tarafı haliyle SharePoint sitenizin context’inde çalışmadığınızdan buradaki verilere ulaşamayacak olmanızdır. Bu konuda SPFx SharePoint Verileriyle Çalışmakisimli kısa yazımda bir örnek yapmış ve bulunduğunuz ortama göre farklı veri doldurma metodları hazırlayarak Local Workbench ile de içinde veri olan (örnek veri) çalışmalar yapabilmenizin yolundan bahsetmiştim.
Güzel olan bir noktayı daha yeniden hatırlatmak istiyorum. Yerel bilgisayarınızda hazırladığınız SPFx webpartınızı herhangi bir yaygınlaştırmaya gerek duymadan, doğrudan SharePoint Online tenant Workbench adresinizi yazarak gerçek verilerle de test edebilirsiniz. Burada tamamen sizin yerel bilgisayarınızdaki kaynaklar kullanılacaktır.
Önceki kısa yazılarımda SPFx’in ne olduğu ve geliştirme ortamını oluşturarak SPFx ile ilk örnek uygulamanın hazırlanması konularından bahsetmeye çalışmıştım. Bu yazılara aşağıdaki bağlantılardan erişebilirsiniz.
Şimdi yine bir örnek ile devam edip SharePoint verisine erişmek noktasında neler yapabiliriz buna değinmek istiyorum. Yeni bir örnek webpart projesi oluşturacağım, sonrasında içerisindeki gereksiz bölümleri temizleyip SharePoint sitesi altındaki liste isimlerini ekrana getiren bir yapı oluşturmaya çalışalım.
Öncelikle npm aracılığı ile gulp yüklemesini yapıyorduk. Bunun için aşağıdaki komut işimizi görecektir.
1
npm install-gyo gulp
Sonrasında SharePoint generator objelerinin yüklenmesini sağlayabiliriyoruz. Bunun için de aşağıdaki komutu çalıştırmanız yeterli olacaktır.
1
npm install-g@Microsoft/generator-SharePoint
Ve son olarak webpart’ın yaratılmasını sağlamak için aşağıdaki komut ile ilerliyoruz.
1
yo@microsoft/SharePoint
Bu adımların sonrasında gulp serve komutunu çalıştırarak uygulamanın local workbench üzerinde çalışmasını sağlayabiliyoruz. Bu bölümde uygulamayı yaratma kısmını hızlıca geçmeye çalışıyorum, zira yukarıda bağlantısını verdiğim SPFx Merhaba Dünya yazısında bu konunun detaylarına ayrıca değinmiştik.
1
code.
komutunu çalıştırarak Visual Studio Code içerisinde projemizin açılmasını sağlayabiliriz. Bir önceki örnekte “Merhaba Dünya” demenin yanı sıra ToolPane için yeni propertyler tanımlama, bunlara varsayılan değer girişi ve önyüzde kullanımını örneklemeye çalışmıştık. Şimdi ise projemize yeni class’lar eklemek, buna metodlar yazmak, test verisi oluşturmak ve hem local workbench hem de SharePoint Online üzerinden veriye ulaşmak noktasına bakmaya çalışacağız.
Burada önemli konulardan bir tanesi local Workbench. Çünkü local workbench aslında SharePoint ortamındaymışız gibi bir arayüzü bizim için oluşturan ama aslında SharePoint olmayan bir ortam. Dolayısıyla bir veri, liste, vb söz konusu değil. Peki local workbench ile çalışırken bu veriye nasıl ulaşabileceğiz?
Local Workbench İçin Test Verisi Oluşturmak
Ben bu ismi vereceğim, çünkü yaptığımız iş aslında local workbench’de olmayan bir veriyi kodumuzu test edebilmek adına oluşturmak. Bunu test metodları yazmaya benzetebilirsiniz. Tabi kodumuzun hem local workbench’de hem de SharePoint Online’daki gerçek verilerle çalışabilmesi için bir dizi düzenleme yapmak durumundayız.
Öncelikle bu test verilerini oluşturmak ve metodlara ulaşabilmek için projemize yeni bir class eklememiz gerekiyor. Bunun için webpart dosyanızı seçili hale getirin ve “New File” butonunu tıklayın.
Oluşturacağımız dosyanın adını SampleHttpClient.ts şeklinde verebiliriz. Burada daha sonra oluşturacağımız ve webpart dosyamızın içinde belirteceğimiz ISPList ve ISPLists isimli interfaceler için tanımlamalar ve metodlar hazırlayacağız. Örnek olarak dosya içeriğimiz şu şekilde olacak.
SampleHttpClient.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import{ISPList}from'./WorkWithSpDataWebPart';
exportdefaultclassSampleHttpClient{
privatestatic_items:ISPList[]=[{Title:'Sample List 1',Id:'1'},
Şimdi webpartımızın içerisinde hem oluşturduğumuz bu yeni class’ı, hem bununla bağlantılı interfacelerimizi, hem de kullanacağımız SPHttpClient nesnesi için gerekli tanımlamaları gerçekleştirelim. Bu bölümde “import” tagını kullanacağız ve kullanmak istediğimiz kütüphaneleri de webpartımızın içerisinde tanımlamış olacağız.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import SampleHttpClient from'./SampleHttpClient';
import{
SPHttpClient
}from'@microsoft/sp-http';
import{
Environment,
EnvironmentType
}from'@microsoft/sp-core-library';
exportinterfaceISPLists{
value:ISPList[];
}
exportinterfaceISPList{
Title:string;
Id:string;
}
Şimdi iki tane metoda ihtiyacımız var. Bunlardan bir tanesi local workbench üzerinde çalışırken bize örnek verilerle yardımcı olacak olan metod, diğeri ise SharePoint Online’da çalıştığımız senaryoda bize ilgili site altındaki gerçek liste bilgilerini getirecek olan metod.
Gerçek datayı alırken verileri çekmek için web api’yi kullanıyoruz ve sonuç bize json olarak geri dönecek. Bu işlemi yaparken siz farklı filtreler kullanabilirsiniz. Ben sadece hidden listelerin veri olarak gelmesini istemediğimden bu bölümde buna ilişkin bir filtre kullandım.
Tabi kodumuz çalıştığında bizim hangi ortamda olduğumuzu anlamalı ve buna göre yukarıdaki metodlardan hangisini çalıştıracağını algılamalı. Bunun için aslında üst bölümde ilk import ve tanımlamaları yaparken yararlanabileceğimiz bir sp-core-library importu da yapmıştık. Aşağıdaki şekilde;
1
2
3
4
import{
Environment,
EnvironmentType
}from'@microsoft/sp-core-library';
Buradan alacağımız Environment değerini kontrol eden bir metod ile local workbench’demiyiz yoksa SharePoint ortamında mı anlayabiliriz. Kontrol kodumuz şöyle olacak.
Bu bölümde EnvironmentType.Local enum’u local workbench’i temsil ediyor ve buna göre getSampleListData() metodunu çağırıyor, yani bizim örnek data dediğimiz bölümü. Koşulun ikinci bölümünde ise EnvironmentType.SharePoint ve EnvironmentType.ClassicSharePoint yer alıyor. Bu iki seçenek sizlerinde anlayacağı üzere modern arayüz ve klasik arayüzü temsil ediyor. Ve bu durumda ise web api aracılığı ile getirdiğimiz gerçek ortam SharePoint verileri geliyor karşımıza.
Bu bölümde kullandığımız ama henüz implemente etmediğimiz bir _renderList() metodumuz var. Bu ise artık oluşan çıktıyı html olarak ekrana döndürme bölümümüz ve şu şekilde olacak.
Ve tabi #spListContainer içeriğini body’nin render edildiği zaman ekrana yerleştirmek. Bunun için bir div kullanabiliriz.
1
<div id="spListContainer"/>`;
Uygulamayı bu şekliyle local workbench’de çalıştırdığımızda aşağıdaki gibi bir çıktı ile karşılaşacağız.
Bu işlemi SharePoint Online workbench’de denediğimizde ise kod içinde web api için belirttiğimiz URL’deki sitenin altında yer alan listeleri ekrana getirecektir.
Uygulamaya ilişkin projenin tamamına GitHubüzerinden erişebilirsiniz.
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.
1
npm install-gyo gulp
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.
1
npm install-g@microsoft/generator-SharePoint
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 buradantemin 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.
1
yo@microsoft/sharepoint
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.
1
gulp trust-dev-cert
Şimdi komutumuzu çalıştırarak paketleme işlemini ve ardından çalıştırmayı gerçekleştirebiliriz.
1
gulp serve
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.
1
explorer.
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.
1
code.
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.
1
2
3
4
5
6
7
exportinterfaceIHelloWorldWebPartProps{
description:string;
test:string;
test1:boolean;
test2:string;
test3:boolean;
}
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ı.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
"preconfiguredEntries":[{
"groupId":"98b9f336-3435-4867-b443-c0be54ec4402",
"group":{"default":"Under Development"},
"title":{"default":"HelloWorld"},
"description":{"default":"First SPFx webpart"},
"officeFabricIconFontName":"Page",
"properties":{
"description":"HelloWorld",
"test":"Multi-line text field",
"test1":true,
"test2":"2",
"test3":true
}
}]
Ö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.
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.
Son günlerde yayınlanan SharePoint Feature Pack 2 ile beraber adını sıkça duymaya başladığımız, aslında geçtiğimiz yıl preview olarak duyurulmuş olan SharePoint Framework (SPFx) ile ilgili kısa birkaç bilgi paylaşarak başlamak istiyorum. Bundan sonra gelecek kısa yazılarımda da bu konuda farklı örneklere yer vermeye çalışacağım ancak öncelikle nedir bu SharePoint Framework (SPFx), bize ne gibi avantajlar sunacak veya ne gibi eksikleri var onlara bakmakta yarar görüyorum. Ardından geliştirme ortamımızı oluşturacak ve bir klasiği bozmadan, “Merhaba Dünya” diyerek devam edeceğiz elbette. Sonrasında ise biraz daha gerçek hayat örnekleri ve sorunları çözme yollarıyla devam edebiliriz.
SPFx client-side SharePoint geliştirme yapmanıza imkan veren bir sayfa ve webpart modeli olarak kısaca özetlenebilir. SharePoint verileri ile hızlıca entegre olabilen, open source araç/kaynak kullanma konusunda destek veren bir yapısı var. Klasik server-side SharePoint geliştirmede kısmen mahkum kaldığımız yeni nesil web teknolojilerini rahatlıkla kullanmamıza imkan veriyor. SharePoint Online için zaten kullanım imkanı varken, Feature Pack 2 ile beraber artık on-premise ortamda da kullanım desteğimiz sunulmuş durumda. On-premise ortamda kullanabilmek için September 2017 güncellemesi olarak da geçen Feature Pack 2 kurulumunu yapmış olmanız gerekiyor.
SharePoint Framework için ana özellikleri listeleyecek olursak.
Bağlantı sağlamış olan kullanıcı ve connection contextini kullanabiliyoruz. Burada herhangi bir iframe veya benzeri yapı söz konusu değil, javascript doğrudan sayfa içerisine ekleniyor.
Sayfada kullandığınız kontroller ayrı bir yapı üzerinde değil, doğrudan DOM içerisinde render ediliyor.
Kullanılan kontroller responsive özellikte.
Sayfanın yaşam döngüsüne bir geliştirici olarak müdehale edebiliyorsunuz. Mesela render, load, serialize, deserialize, vb.
Herhangi bir javascript framework ile çalışabilirsiniz. Mesela React, Knockout, Angular, Handlebars, vb.
Open source geliştirme araçlarını kullanabilirsiniz. Mesela npm, TypeScript, Yeoman, webpack, gulp, vb.
Son kullanıcılar tarafından da kullanılabilecek bir geliştirme yöntemi tabi ki tenant admin tarafından onaylanması durumunda.
Hazırlayacağınız webpartlar hem classic hem de modern sayfalarda kullanılabilir.
SharePoint Framework öncesinde de client-side geliştirme yapabiliyorduk elbette. Bu yöntemleri ve avantaj/dezavantaj incelemesini yapmaya çalışalım kısaca.
JavaScript Injection
SharePoint Online üzerinde, özellikle SandBox geliştirme yapısında kod kullanımımız giderek bloklandıktan sonra en yoğun kullanılan webpart Script Editor’dü sanırım. Kullanım şekli oldukça pratikti. Hazırladığınız JavaScript’i Script Editor webpart içerisine kopyalamanız yeterliydi. Sayfa çalıştırıldığında “page render” işlemi esnasında eklediğiniz script çalıştırılıyordu. İlk avantajı sanırım kolay olması. Kullanımı kolay, test etmesi kolay, tarayıcı üzerindeki araçlar aracılığı ile debug etmesi kolay. Diğer avantajlı kısmı ise aynı DOM ve aynı browser context’ini kullanıyor olması. Böylece sayfa içerisindeki diğer kontrollere ulaşmak ve dolayısıyla basit entegrasyon ve interaktiviteler sağlamak mümkün. Bu yazacağınız kod ile doğrudan bağlantılı olsa da genel itibariyle performanslı yada UX açısından tüm sayfanın gelmesini beklememe konforu sunması açısından performanslı görünen bir yapıda olduğunu söylemek mümkün.
Dezavantajlı kısımlarına bakacak olursak yine kolay olması burada da ilk maddeye gelecektir sanırım. Bizim için kolay olduğu kadar son kullanıcının sayfayı düzenleme moduna aldığında scripte yapacağı ufak müdehaleler ile fonksiyonaliteyi bozması da çok kolay 🙂 İkinci sorunumuz ise “NoScript” olarak ifade edebileceğimiz feature’ın aktif olduğu senaryolar. Bu feature aktif durumdayken “Add/Customize Pages (ACP)” yetkileriniz alındığından Script Editor ilgili site koleksiyonlarında bloklu duruma gelecektir.
SharePoint Add-in Model
Özellikle NoScript özelliğinin aktif olduğu sitelerde kullanmayı düşündüğümüz geliştirme modellerinden bir tanesi. Bu yöntemi kullandığınızda aslında hazırladığınız geliştirme paketleri bir iFrame yardımıyla sayfaya ekleniyor. iFrame’in responsivite katili olmasını bir tarafa bırakacak olursak özellikle admin rolündeki arkadaşların bu yönteme yönlendirmelerinin altında yatan bir diğer sebep de iFrame olması sebebiyle sayfamız ile aynı DOM’u ve context’i kullanmıyor olduğundan güvenli bulunuyor olması. Tabi aynı DOM ve context’i kullanamıyor olmanın verdiği dezavantaj ayrıca değerlendirilmeli.
Dezavantajlarına bakacak olursak öncelikle Script Editor’a göre çok daha yavaş çalışan bir mekanizması olduğunu söylemek mümkün. Bunun nedeni iFrame olarak çalışıyor olması ve aynı DOM’u kullanmıyor olması nedeniyle iFrame’deki sayfayı açmak için ayrı bir request daha göndermek durumunda. Yukarıda da belirttiğim gibi günümüzde artık çok da küçümseyemeyeceğimiz bir diğer dezavantaj ise responsivite noktasında iFrame kaynaklı olarak sorun yaşıyor olmamız.
SharePoint Framework
Son dönemde özellikle bulut kullanımının da yoğunlaşmaya başlaması, Microsoft’un önem verdiği mecralardan birinin on-premise yerine SharePoint Online olması gibi sebeplerle eski geliştirme metodumuz olan full trust C# assembly kullanarak geliştirme tarih olmaya doğru gidiyor. Çok sert oldu, tarih olmayacak elbette ama daha çok on-premise ve hybrid olmayan daha kısıtlı bir domainde hayatını sürdürmeye devam edecek. Yeni nesil geliştirmelerde yerini artık JavaScript tabanlı, arka planda REST çağrıları ile veriye ulaşan veya düzenleyen yapılarda ilerliyoruz. İşte SharePoint Framework (SPFx) bu noktada karşımıza çıkan yeni nesil SharePoint geliştirme modeli diyebiliriz.
SharePoint Framework’ün halen geliştirilmeye devam ettiğini söylemeden geçmek istemiyorum. Hatta şu anda aktif olan bazı bölümler için ileride değişimler de sözkonusu olabilir. Ancak Microsoft bu kısım için geriye dönük destek olacağı sözünü veriyor. Dolayısıyla “beklemeyin, geliştirin” diyor bize.
Microsoft tarafından ürün için paylaşılmış eski tarihli bir road map var ancak yenisi Ekim ayı içerisinde yayınlanacak, bunun ile ilgili road map’in yayınlanması sonrası bir şeyler yazmayı daha doğru buluyorum.
Bitirmeden önce bizi doğrudan ilgilendirecek bir known-issue’dan da haberdar etmek isterim. Eğer geliştirme esnasında tarayıcı olarak Chrome kullanıyorsanız Workbench’in kullanımında geliştirici sertifikası konusunda sorun yaşayabilirsiniz. Bu durumda “Your connection is not private” hata mesajı sonrasında çalışmanızı devam ettirebilirsiniz. Tüm bilinen hataların güncellendiği adrese buradan erişebilirsiniz.
Geliştirme Araçlar
SharePoint Framework ile clien-side geliştirmede aşağıdaki kod editörlerini kullanabilirsiniz.
