IOrganizationService Retrieve Metodu

Bu yazı 25 Mayıs 2019 tarihinde Medium/@dynamics365 altında yayınlanmıştır. 21 Mayıs 2020 tarihinde emregulcan.com altında taşınmıştır.

Merhaba,

Bu yazıda Dynamics 365 CE (CRM) SDK ‘da IOrganizationService interface ‘in sağlamış olduğu Retrieve metodunu inceleyeceğiz.

Retrieve metodu, Dynamics 365 CE (CRM) ‘de herhangi bir kaydı okumamızı / sorgulamamızı sağlamaktadır.

SQL ‘de SELECT sorgusu ile aynı işlemi yapmaktadır, fakat sonunda WHERE kriterine ID parametresi eklenerek sadece ilgili kaydı almamızı sağlar.

Önemli Noktalar

• Retrieve metodu ile kayıt bilgisine ulaşmak için ilgili kaydın Dynamics 365 CE (CRM) ID bilgisine ihtiyacımız vardır.
• Retrive metodu 3 parametre almaktadır. Bunlar string olarak Entity (Varlık) LogicalName bilgisi, GUID formatında ilgili kaydın Id bilgisi ve ColumnSet türünde sonuçta görmek istediğimiz alanları içeren nesnedir.
• Retrieve metodunun geri dönüş türü Entity ‘dir. Eğer göndermiş olduğumuz ID ile ilişkili bir kayıt varsa Entity olarak sonuç döner, hatalı bir ID bilgisi girmişsek ya da ilgili varlıkta bu ID ile ilişkili bir kayıt yoksa -2147220969 kodlu Object Does Not Exist hatası döner. Hata mesajının formatı {EntityLogicalName} With Id = {Entity Record Id} Does Not Exist ‘dir. Örnek olarak contact With Id = a5161572-876b-c911-a888-001d3aa8652a Does Not Exist. Dolayısıyla bu metodu try – catch içinde kullanmak ve gerekli durumlarda kullanıcıya hata göstermek ve log kayıtlarına yazmak doğru olacaktır.
• Retrieve metodu sonuç olarak sadece Dynamics 365 CE (CRM) ‘de data içeren alanları (Column / attribute) içermektedir. Örnek olarak ilgili Entity ‘de 30 alan varsa ve sorguladığınız kayıtta sadece 10 alan dolu ise sonuç kümenizde 10 alan olacaktır. Ayrıca bu alanlarda Field Level Security ‘de uygulanmaktadır, dolayısıyla dönen alanlar buna göre değişecektir.
• Retrieve metodu ile sadece ilgili kaydı okuyabiliriz, ilişkili alt kayıtlarını aynı sonuç kümesi içinde alamayız.
• İşlem yapan kullanıcı (IOrganizationService ‘i oluşturan kimlik sahibi ya da CallerId olarak verilmiş SystemUser) ilgili Entity (Varlık) için Read (Okuma) yetkisine sahip olmalıdır.

İlgili Entity (Varlık) için Ownership (Sahiplik) ayarı User or Team (Kullanıcı veya Takım) ise işlem yapan kullanıcının Read yetkisi buna göre olmalıdır, eğer kayıt üzerinde yetki sahibi değilse Dynamics 365 CE (CRM) aşağıdaki gibi bir hata fırlatacaktır.

Principal user (Id=xxxxx, type=8, roleCount=X, privilegeCount=X, accessMode=x, is missing prvReadContact privilege (Id=xxxxx)

Aslında bu hata sadece Retrieve için değil, tüm operasyonlar için geçerlidir. Dikkat ederseniz işlem yapan kullanıcının (Principal user) prvReadContact yetkisinin olmadığını belirtiyor.

.NET Projesi – Örnek Kod

.NET projelerimizde Microsoft.CrmSdk.CoreAssemblies kütüphanelerini kullanarak Dynamics 365 CE (CRM) ‘de Retrieve işlemi yapabiliriz. Bu kütüphaneleri NuGet üzerinden projemize dahil edebiliriz.

Dynamics 365 CE (CRM) SDK kütüphanelerini projemize nasıl ekleyeceğimizi daha önce burada detaylı olarak anlatmıştım.

Yukarıdaki 2 örnekte tek farklılık ColumnSet parametresine vermiş olduğumuz değerler.

İlk örnekte new ColumnSet(true) olarak gönderdiğimiz değerde true değeri tüm alanları (Column / attribute) almak istediğimizi belirtmekte. SQL ‘de karşılığı SELECT * FROM [tabloadi] komutudur, burada gönderdiğimiz true aslında * ‘dır.

İkinci örnekte ise new ColumnSet("firstname", "lastname", "emailaddress1", …..) olarak değer gönderdik. Burada vermiş olduğumuz değerler ilgili Entity için geçerli olan Column / attribute isimleridir. Böylece sadece ihtiyacımız olan kadar alanı sorguluyoruz. SQL ‘de karşılığı SELECT firstname, lastname, emailaddress1 FROM [tabloadi] komutudur.

Performans sorunu yaşamamak için sadece ihtiyacımız olan alanları sorgulamak çok daha doğru olacaktır, bu nedenle ikinci yöntemi kullanmanızı öneririm.

Retrieve metodunun geri dönüş türü Entity nesnesidir.

İlk örnek üzerinden dönen datayı incelediğimizde aşağıdaki gibi bir sonuç olacaktır.

Daha önce Entity kavramını anlattığım yazıda bahsettiğim üzere Attributes property KeyValuePair<string, object> olarak değer içermektedir, dolayısıyla bu property içinde for ya da foreach ile dönerek ilgili Column (attribute) değerini okuyabiliriz.

Burada önemli olan nokta, işlem yapacağınız alanın (Column / attribute) ilgili kayıtta boş olması ve dolayısıyla dönen sonuçta bulunmaması ihtimalini göz önüne alarak işlem yapmanız.

Örnek olarak emailaddress1 alanı için var email = data['emailaddress1']; olarak okuma işlemi yaptığımızı düşünelim.

Eğer ilgili kayıtta bu alan data içeriyorsa ve Attributes içinde yer alıyorsa sorunsuz olarak email değişkenine bu değeri atayabiliriz.

Fakat sonuç kümemizde emailaddress1 yoksa bu durumda The given key was not present in the dictionary hatası alırız. Bu Dynamics 365 CE (CRM) hatası değil, .NET Framework ‘e ait bir hatadır ve data['KEY'] olarak belirttiğimiz Key değerinin ilgili Collection ‘da bulunmadığını belirtmektedir.

The given key was not present in the dictionary hatası, Dynamics 365 CE (CRM) geliştirmelerinde en çok alınan hata olabilir 🙂

Bu hatanın önüne geçmek için dönen kayıtta ilgili alanın var olup olmadığını kontrol etmeli ve eğer varsa değerini okumalıyız. Bunun için aşağıdaki 2 yöntemden istediğinizi kullanabilirsiniz;

İlk yöntem klasik if ile ilgili Collection içinde Key olup olmadığını kontrol edip, eğer varsa değerini okuyoruz.

İkinci yöntem ise Dynamics 365 CE (CRM) SDK ‘da yer alan Generic bir metot ve vermiş olduğumuz parametreye göre ilgili alanı kontrol edip, değerini <T> ‘de belirttiğimiz türe dönüştürmektedir. Bu metodun kullanımında önemli olan nokta ilgili alanın data türünü bilmemizdir.

GetAttributeValue<T> metodunun en önemli özelliği; sorguladığımız alan sonuç kümesinde yoksa hata oluşturmak yerine <T> ‘ye vermiş olduğumuz değerin default değerini ya da Null değer dönmesidir.

GetAttributeValue<T> ‘nin geri dönüş değerleri için detaylı bilgiye buradan erişebilirsiniz.

Attributes üzerinden okuyacağımız tüm değerler database ‘de olan değerlerdir, eğer işlem yapan kullanıcının dil, timezone vb. ayarlarına göre Dynamics 365 CE (CRM) arayüzünde görüldüğü gibi değer okumak istersek FormattedValues üzerinden işlem yapabiliriz.

FormattedValues, KeyValuePair<string, string> olarak değer tutmaktadır, dolayısıyla tüm alanlar için geri dönüş tipi string olacaktır.

Örnek olarak gendercode alanı üzerinden cinsiyet bilgisini okumak istersek aşağıdaki gibi işlem yapabiliriz.

Bu örnekte ilk satır OptionSetValue türünde değer dönecek, bu durumda genderTypeCode.Value ile ilgili alanın database değerini alabiliriz. Bu alan OptionSet olduğu için Value değeri Integer ‘dır.

İkinci satırda FormattedValues["gendercode"] ise, işlem yapan kullanıcının Dil ayarlarına göre (varsa) ilgili alanın değerini string olarak dönecektir, yani Erkek, Kadın gibi bir değer içerecektir. Eğer kullanıcı dilinde çeviri bilgisi yoksa default değerleri dönecektir.

Umarım faydalı bir yazı olmuştur.

IOrganizationService metotları için oluşturduğum Index yazısına buradan ulaşabilirsiniz.

Dynamics 365 CE (CRM) SDK konusunda ilgili tüm yazılara tek nokta üzerinden ulaşmak isterseniz http://www.emregulcan.com/dynamics365-sdk adresine bakabilirsiniz.