SharePoint Framework'te Eski Kullanıcı Ayarlarını Yönetmek

SPFx'te Eski Kullanıcı Ayarları Neden Sorun Oluyor?

SharePoint Framework (SPFx) 1.18 ve sonrasında Microsoft'un Entra ID entegrasyonunu köklü biçimde değiştirmesi, mevcut web part'larda saklanan kullanıcı tercihlerini doğrudan etkiledi. Daha önceki sürümlerde geliştiriciler genellikle web part properties, localStorage ya da SharePoint kullanıcı profil özellikleri (User Profile Service) üzerinden kişiselleştirme verisi tutuyordu. Ancak Entra ID uygulama kaydı modelinin değişmesiyle birlikte, özellikle API çağrıları üzerinden profil verisi okuyan/yazan bileşenler sessizce bozulmaya başladı.

Bu yazıda pratikte karşılaştığımız senaryoları ve her biri için uyguladığımız çözüm yollarını paylaşıyoruz.

Hangi Depolama Yöntemi, Hangi Durumda?

SPFx'te kullanıcı ayarlarını saklamanın birden fazla yolu var. Hangisinin kullanıldığını anlamak, migrasyon stratejisini belirliyor:

• Web Part Properties (PropertyPane): Sayfa düzenleyicisi üzerinden yapılandırılan değerler. Sayfa JSON'ında saklanır. Kullanıcıya özel değildir; sayfayı düzenleyen herkes değiştirebilir. Genellikle görünüm tercihleri (kaç öğe gösterilsin, hangi liste kullanılsın) için kullanılır.
• localStorage / sessionStorage: Tarayıcı tarafında saklanan geçici veriler. Kullanıcıya özeldir ancak cihaza bağlıdır; farklı tarayıcıda veya cihazda kaybolur. Tema tercihi, sidebar durumu gibi hafif veriler için uygundur.
• SharePoint User Profile Properties: Sunucu tarafında, kullanıcının profil kaydına bağlı özel özellikler. Tüm cihazlarda tutarlıdır ancak okuma/yazma Graph API veya eski CSOM çağrıları gerektirir. Entra ID değişikliklerinden en çok etkilenen yöntem budur.
• SharePoint List / Hidden List: Kullanıcı başına bir satır tutan özel bir liste. Tam kontrol sağlar, ancak performans ve izin yönetimi dikkat gerektirir.

Entra ID Uygulama Kaydı Değişiklikleri: Ne Oldu?

SPFx 1.18 öncesinde, çoğu SPFx çözümü SharePoint Online Client Extensibility adlı paylaşılan bir Entra ID uygulaması üzerinden API çağrısı yapıyordu. Bu uygulama, kiracı (tenant) yöneticisinin onayladığı izinleri toplu olarak barındırıyordu. Geliştiriciler AadHttpClient veya MSGraphClient ile bu izinleri kullanarak Graph API'ye erişebiliyordu.

Yeni modelde Microsoft, her SPFx çözümü için ayrı uygulama kaydı oluşturulmasını teşvik ediyor. Bu yaklaşım güvenlik açısından daha sağlıklı (en az yetki prensibi) ancak mevcut çözümlerde şu sorunları yaratıyor:

• Eski izin onayları (webApiPermissionRequests) geçersiz kalabiliyor.
• AadHttpClient ile yapılan çağrılar, yeni uygulama kaydına yönlendirilmediği sürece 401/403 hatası veriyor.
• Kullanıcı profil özelliklerine yazan çözümler, User.ReadWrite yerine daha spesifik scope'lar gerektiriyor.

Pratik Etki: Profil Tabanlı Ayarlar

Bir müşteri projemizde SPFx web part'ı, kullanıcının tercih ettiği dili ve bildirim sıklığını SharePoint User Profile üzerindeki özel özelliklere yazıyordu. SPFx 1.19'a yükselttikten sonra bu çağrılar sessizce başarısız olmaya başladı; web part hata vermiyordu ama tercihler kaydedilmiyordu. Kök neden, eski paylaşılan uygulama kaydındaki User.ReadWrite.All izninin yeni modelde kaldırılmış olmasıydı.

Migrasyon Stratejileri

1. Profil Özelliklerinden Graph API'ye Geçiş

SharePoint User Profile Service yerine Microsoft Graph User Settings veya Open Extensions kullanmak, hem daha modern hem de Entra ID uyumlu bir yaklaşım. Graph Open Extensions ile kullanıcıya özel JSON verisi saklayabilirsiniz:

• Graph API endpoint'i: PATCH /me/extensions/{extensionId}
• Gerekli izin: User.ReadWrite (delegated)
• Veri formatı: serbest JSON, 2KB sınırı

Mevcut profil verisini okuyup Graph extension'a yazan bir seferlik migrasyon scripti hazırlamak genellikle en temiz yoldur. Biz bunu Power Automate akışı ile yaptık: mevcut kullanıcı profil özelliğini oku, Graph'a yaz, eski özelliği temizle.

2. localStorage Verilerini Koruma

localStorage verisi tarayıcıda kalır ve SPFx güncellemesinden doğrudan etkilenmez. Ancak dikkat edilmesi gereken bir nokta var: SPFx web part'ınızın manifest ID'si değişirse (örneğin yeni bir çözüm paketi oluşturduysanız), localStorage key'leri artık eşleşmeyebilir.

Bunu önlemek için localStorage key'lerinizi web part instance ID'si yerine sabit bir namespace ile oluşturun. Örneğin fiboo-userprefs-{loginName} gibi bir şema, web part yeniden deploy edilse bile veriyi korur.

3. Hidden List Yaklaşımı

Karmaşık kullanıcı tercihleri (çoklu filtre durumları, dashboard düzeni, favori öğeler) için en güvenilir yöntem, site koleksiyonunda gizli bir liste oluşturmaktır. Bu listenin avantajları:

• Entra ID değişikliklerinden bağımsız — standart SharePoint REST API ile erişilir.
• Kullanıcı başına satır, tüm cihazlarda tutarlı.
• Versiyon geçmişi ile audit trail sağlar.
• Yönetici, gerektiğinde kullanıcı ayarlarını toplu düzenleyebilir.

Dezavantajı performanstır: her sayfa yüklemesinde bir REST çağrısı yapılır. Bunu azaltmak için verileri sessionStorage içinde önbelleğe alıp, belirli aralıklarla (örneğin 15 dakika) sunucuyla senkronize etmek etkili bir desen.

Mevcut Çözümleri Denetleme Kontrol Listesi

SPFx çözümlerinizde eski kullanıcı ayarlarını tespit etmek için şu adımları izleyin:

• package-solution.json dosyasındaki webApiPermissionRequests bölümünü kontrol edin. Burada tanımlı izinler hâlâ geçerli mi?
• AadHttpClient veya MSGraphClient kullanımlarını arayın. Bu çağrılar hangi izinlere bağımlı?
• SPHttpClient ile User Profile endpoint'lerine yapılan çağrıları belirleyin (/_api/SP.UserProfiles.PeopleManager).
• localStorage/sessionStorage key'lerini listeleyin ve bunların web part lifecycle'ından bağımsız olup olmadığını doğrulayın.
• Çözümün tenant-scoped mı yoksa site-scoped mı deploy edildiğini kontrol edin; bu, izin modelini etkiler.

Sonuç Yerine: Adım Adım Yaklaşım

SPFx'teki Entra ID değişiklikleri, kullanıcı ayarlarını yöneten çözümler için gerçek bir risk oluşturuyor — ama erken tespit edilirse yönetilebilir bir risk. Önerimiz şu: önce mevcut depolama yöntemlerini haritalayın, ardından her biri için hedef mimariyi belirleyin ve migrasyon işlemini aşamalı olarak uygulayın. Tek seferde büyük bir refaktör yerine, web part'ları birer birer güncellemek hem riski azaltır hem de kullanıcı deneyimini kesintiye uğratmaz.