Visual Studio (C#) projelerinde Dynamics 365 CE ‘e Erişim

Bu yazı 02 Mart 2019 tarihinde Medium/@dynamics365 altında yayınlanmıştır. 26 Nisan 2020 tarihinde emregulcan.com altında taşınmıştır.

İçerikler, yazının oluşturulduğu tarih için geçerli olup, Microsoft Dynamics 365 CE, Power Platform ve Azure hizmetlerinin sürekli iyileştirme ve güncelleme döngüsünden dolayı paylaşılan bilgilerde değişiklikler meydana gelmiş olabilir.

Merhaba,

Bu yazımızda C# ile geliştirdiğimiz projelerimizde Dynamics 365 CE (CRM) web servislerine nasıl bağlanacağımızı tüm detaylarıyla adım adım inceleyeceğiz.

Eğer Dynamics 365 CE (CRM) SDK hakkında yada nasıl indirileceği konusunda bilgi sahibi değilseniz önceki yazımı okumanızı tavsiye ederim.

Bu örnekte ilk olarak Console Application üzerinde geliştirme yapacağız, sonrasında ise ilerleyen konularımızda kolaylık sağlaması için bu bağlantı işlemlerini bir library üzerine taşıyacağız.

İlk olarak Dynamics 365 CE SDK bileşenlerini projemize eklememiz gerekli.

Bunun için projemize sağ tıklayıp Manage NuGet Packages menüsünü kullanabiliriz.

Açılan ekranda Browse sekmesinde arama bölümüne Microsoft.CrmSdk.CoreAssemblies ya da kısaca CrmSdk yazarak ilgili bileşenlere ulaşabiliriz.

Bu yazıyı hazırladığım tarihte en güncel sürüm 9.0.2.12 olarak yayınlanmış durumda. Eğer Dynamics 365 CE Online kullanıyorsanız son sürümü kullanmanızı öneririm, on-prem ortamlarda ise ilgili sürüme göre SDK kullanmanız gerekmekte.

Alternatif olarak Package Manager Console üzerinden Install-Package Microsoft.CrmSdk.CoreAssemblies komutunu kullanarak ilgili projeye gerekli bileşenleri ekleyebilirisiniz.

9.0.2.9 ve sonrası sürümlerde yükleme aşamasında Attempting to gather dependency information for packege ‘Microsoft.CrmSdk.CoreAssemblies.9.0.2.12’ with respect to project ‘PROJECT_NAME’, targetting ‘.NETFramework, Version=v4.5.2’ gibi bir hata alırsanız, çalıştığınız projenin .NET Framework sürüm bilgisini yükseltmeniz gerekecektir.

https://www.nuget.org/packages/Microsoft.CrmSdk.CoreAssemblies adresinde görebileceğiniz üzere projelerimizde CRM SDK 9.0.2.9 ve sonrasını kullanmak istiyorsak projemizin .NET Framework sürüm bilgisi minimum 4.6.2 olmalıdır.

Eğer projenizin .NET Framework sürümünü çeşitli nedenlerden dolayı yükseltemiyorsanız ve .NET Framework 4.5.2 ve altında ise, Dynamics 365 SDK için 9.0.2.5 ve altındaki sürümleri kullanabilirsiniz.

Bu durumda OrganizationService bağlantısı aşamasında Metadata contains a reference that cannot be resolved : ‘https://organizationname.crm4.dynamics.com/?wsdl=sdkversion=9’ şeklinde genel bir hata alırsınız. Hatanın detaylarına (InnerException) baktığımızda ise Unable to read data from the transport connection : An existing connection was forcibly close by the remote host , The underlying connection was closed : An unexpected error occured on a send. mesajlarını bulabilirsiniz.

Bu hatanın nedeni Microsoft ‘un Dynamics 365 CE (CRM) için TLS 1.2 güncellemesi yapması ve bunu zorunlu hale getirmesidir. Hatayı önlemek için IOrganizationService oluşturmadan önce aşağıdaki kodu eklemeniz gerekmektedir.

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12

Yükleme işlemi tamamlandığında projemizin References altında Microsoft.Crm.Sdk.Proxy ve Microsoft.Xrm.Sdk dll ‘leri yer alacaktır.

Dynamics 365 CE (CRM) ‘e bağlanabilmek için OrganizationService url bilgisine ihtiyacımız bulunmakta. Bu adresi alabilmek için aşağıdaki adımları takip edebilirsiniz.

Dynamics 365 ana menüsü üzerinden Settings (Ayarlar)> Customizations (Özelleştirmeler)> Developer Resources (Geliştirici Kaynakları) bağlantılarını kullanarak ilgili sayfaya erişmeliyiz.

Developer Resources sayfasında Dynamics 365 CE (CRM) için bir çok teknik detay yer almaktadır.

Bu yazımızın konusu OrganizationService ‘e bağlanmak olduğu için bizim için önemli kısım OrganizationService bölümünde bulunan url bilgisi.

Bu url standart olarak https://ORGANIZASYONADI.api.crm4.dynamics.com/XRMServices/2011/Organization.svc formatındadır. ORGANIZASYONADI olarak belirttiğim bilgi, Dynamics 365 CE Online Deneme Ortamı Oluşturmak başlıklı yazımda bahsettiğim kayıt aşamasında belirlediğimiz isimdir. crm4 ise, yine aynı yazıda bahsettiğim Dynamics 365 CE ‘nin bulunduğu region (bölge) ile ilgilidir, Türkiye ‘den alınan Dynamics 365 CE instance ‘lar crm4 region ‘da yer almaktadır.

Bu arada unutmamamız gereken önemli bir nokta, geçtiğimiz yıllarda Dynamics 2016 Service Pack 1 ile birlikte (sürüm 8.1) Microsoft OrganizationService ‘i (2011 endpoint yada SOAP endpoint olarakta anılmakta) sonlandırma kararı aldı (deprecated), fakat henüz tam anlamıyla sonlandırılmış değil. Bundan sonra OrganizationService yerine WebAPI kullanarak bağlantı kurmamız gerekiyor.

Dynamics 365 CE SDK tarafında bu geçiş Microsoft tarafından otomatik olarak yapılacak ve kodlar WebAPI destekli olarak çalışacak.

https://docs.microsoft.com/en-us/previous-versions/dynamicscrm-2016/developers-guide/dn281891(v=crm.8) adresinden detaylara ulaşabilirsiniz.

Artık Dynamics 365 CE (CRM) OrganizationService ‘e bağlanmak için herşey tamam, şimdi kod yazma zamanı 🙂

Dynamics 365 CE (CRM) OrganizationService ‘e bağlanmak için birden fazla alternatif yöntem mevcut, bunların en basiti, işlem yapacağımız kullanıcının kullanıcı adı ve parola bilgisi ile yaptığımız bağlantıdır.

Altarnate_01 isimli metotda görüldüğü gibi OrganizationServiceProxy nesnesi üretiyoruz ve bunu IOrganizationService olarak cast edip kullanıyoruz.

İkinci yöntem; Alternate_02 isimli metodumuzda kullandığımız XrmTooling ile CrmServiceClient oluşturmak.

Bunun için projemize Microsoft.CrmSdk.XrmTooling.CoreAssembly bileşenini eklememiz gerekli. CoreAssemblies ‘de olduğu gibi NuGet üzerinden ilgili bileşenleri ekleyebilirsiniz yada Package Manager Console üzerinden Install-Package Microsoft.CrmSdk.XrmTooling.CoreAssembly komutunu çalıştırabilirsiniz.

CrmServiceClient, SQL connection string ifadelerine benzer şekilde, Dynamics 365 CE ‘e özel bir yapıda bağlantı bilgileri içerir.

İlgili connectionstring ‘lerin kullanım şekilleri için https://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/developer/xrm-tooling/use-connection-strings-xrm-tooling-connect#connection-string-examples adresine bakabilirsiniz.

Bu bilgileri projemizin app.config ya da web.config dosyası içinde <connectionStrings> node altında ya da herhangi bir güvenli yapıda saklayabiliriz. Bu yazıda anlattığım örneklerde app.config kullanacağım.

Burada altını kırmızı ile reklendirdiğim Username ve Password alanları Dynamics 365 CE (CRM) ‘e bağlanmak istediğiniz kullanıcının bilgilerini içermektedir. username bilgisi kullanıcı@organizasyon.onmicrosoft.com formatında olmalıdır.

Connection bilgisi için tanımladığımız ad (name) bilgisini (örnek : D365TR_Sandbox), kodumuzda bu bilgiyi çağırmak için kullanacağız.

Alternate_02 metodumuzda görüldüğü üzere ilk olarak app/web.config dosyamızdan D365TR_Sandbox isimli connectionstring değerimizi okuyoruz. Bunun için projemizde using System.Configuration; namespace eklemesi yapmamız gerekli.

Sonrasında CrmServiceClient constructor ‘a bu connectionstring ‘i parametre olarak gönderiyoruz. Aslında işlemimiz burada bitiyor, çünkü CrmServiceClient tek başına bize birçok metot sunuyor ve direkt olarak Dynamics 365 CE (CRM) ile işlem yapmamıza imkan tanıyor.

Fakat projelerimizde IOrganizationService ‘e ihtiyaç duyabileceğimiz yerler olabileceği için kodumuzda CrmServiceClient.OrganizationServiceProxy ya da CrmServiceClient.OrganizationWebProxyClient property ‘lerini IOrganizationService ‘e cast ediyoruz.

CrmServiceClient ve desteklediği işlemler hakkında detaylı bilgiye https://docs.microsoft.com/en-us/dotnet/api/microsoft.xrm.tooling.connector.crmserviceclient?view=dynamics-xrmtooling-ce-9 adresinden erişebilirsiniz.

İki alternatif yöntem ile IOrganizationService nesnemizi oluşturduk, bu metotların proje içinde kullanımı aşağıdaki gibidir;

Örnek kodumuzda yer alan WhoAmIRequest Dynamics 365 CE SDK ‘da yer alan bir request yapısıdır ve o anda IOrganizationService ‘e bağlanmış kullanıcının bilgilerini WhoAmIResponse olarak döner. Yapmış olduğumuz bağlantı işlemlerini kontrol etmenin ve kullanıcıya ait bilgileri almanın en kolay yoludur.

Bunların dışında farklı bir alternatif olan Server-to-Server (S2S) Authentication kurgusunu başka bir yazıda detaylı olarak anlatacağım.

Dynamics 365 CE (CRM) OrganizationService bağlantı işlemlerinde unutulmaması gereken önemli noktalar aşağıdaki gibidir;

• OrganizationService thread-safe değildir. Eğer uygulamanız multi-thread olarak çalışıyorsa, her bir thread kendine ait OrganizationServiceProxy oluşturmaktadır.
• OrganizationServiceProxy constructor her çağrıldığında Dynamics 365 CE (CRM) tarafında 2 işlem yapılmaktadır;
  • Metadata download
  • Kullanıcı authentication işlemi

Bu 2 madde performans açısından önemlidir ve dikkate alınmalıdır.

Performans konusunda önerileri ve dikkat edilmesi gereken noktaları farklı bir yazıda detaylı olarak anlatacağım.

Başlangıçta belirttiğim gibi sonraki yazılarda geliştireceğimiz örnek projelerde de aynı bağlantı yapısını kullanabilmek için kodlarımızı bir helper proje içinde yeniden yapılandırdım.

Metotlarda gördüğünüz callerId parametresi bir sonraki yazımızın konusu. Hazırladığımız ConnectionHelper ‘ı projelerimizde aşağıdaki gibi kullanabiliriz;

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

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.