Giriş

Serinin önceki yazısında Visual Studio 2022′yi Power Platform üzerinde oluşturduğumuz developer-enabled UDE ortamına bağlamıştık. Environment URL ve Finance and Operations URL ayrımını, Connect to Dataverse adımını, Finance & Operations assets indirme sürecini, metadata configuration kontrolünü ve Application Explorer’ın doğru açıldığını nasıl doğrulayacağımızı ele almıştık.

Bu yazıda artık bir adım daha ileri gidiyoruz. Bağlantısı tamamlanmış bir UDE ortamında yeni bir model oluşturacağız, bu modeli doğru package yapısı içinde konumlandıracağız, Visual Studio’da bir Operations Project açacağız ve ilk basit X++ geliştirmemizi yapacağız.

Klasik development VM modelinden gelen geliştiriciler için burada hem tanıdık hem de farklı noktalar var. Model, package, project, Application Explorer ve build kavramları tanıdık. Fakat UDE ile birlikte geliştirme tier’ı ve çalışma tier’ı ayrıldığı için bazı alışkanlıkları yeniden düşünmek gerekiyor. Kod ve metadata lokal bilgisayarda hazırlanıyor; çalışma, deploy ve test ise buluttaki Finance & Operations runtime üzerinde gerçekleşiyor.

Bu ayrımı doğru anlamak, UDE üzerinde sağlıklı geliştirme yapmanın temel şartlarından biri. Çünkü lokal bilgisayarda bir X++ nesnesini oluşturmak ve build etmek, onun otomatik olarak cloud runtime’da çalışacağı anlamına gelmiyor. Çalıştırma ve test için ilgili modelin online UDE ortamına deploy edilmesi gerekiyor. Bu yazıda önceliği model, proje ve ilk build tarafına vereceğim; deploy ve debug tarafını ise kısa bir girişle ele alıp sonraki yazıya bağlayacağım.

Bu yazıda ne yapacağız?

Bu yazının amacı, UDE ortamına bağlanmış Visual Studio üzerinde ilk geliştirme akışını uçtan uca anlamak. Özellikle ilk denemede çok karmaşık bir senaryo seçmek yerine, basit ve kontrollü bir örnekle ilerlemek daha doğru olur.

Bu kapsamda aşağıdaki adımları ele alacağız:

• UDE’de development tier ve execution tier ayrımını kısaca hatırlayacağız.
• Model, package ve project kavramlarını UDE açısından konumlandıracağız.
• Yeni bir model oluşturacağız.
• Model için yeni package mı yoksa mevcut package mı kullanılmalı sorusunu değerlendireceğiz.
• Referenced packages seçimini basit bir örnek üzerinden açıklayacağız.
• Visual Studio’da Operations Project oluşturacağız.
• Projeyi oluşturduğumuz model ile ilişkilendireceğiz.
• İlk runnable X++ class nesnesini ekleyeceğiz.
• Basit bir X++ kodu yazıp build alacağız.
• Output penceresi üzerinden build sonucunu kontrol edeceğiz.
• Deploy/debug tarafına geçmeden önce kontrol listesi çıkaracağız.

Böylece UDE üzerinde ilk kez X++ geliştirme yapan biri için “bağlandım, şimdi ne yapacağım?” sorusuna pratik bir cevap vermiş olacağız.

Başlamadan önce kontrol listesi

Bu yazıya başlamadan önce Bölüm 5′teki bağlantı adımlarının tamamlanmış olması gerekir. Aksi durumda model oluşturma veya project açma adımlarında farklı hatalarla karşılaşılabilir.

• Visual Studio 2022 açılabiliyor olmalı.
• Power Platform Tools for Visual Studio extension kurulmuş olmalı.
• Finance & Operations Visual Studio extension kurulmuş olmalı.
• Connect to Dataverse ile doğru UDE ortamına bağlanılmış olmalı.
• Assets ve metadata download işlemleri tamamlanmış olmalı.
• Configure Metadata ekranında aktif metadata configuration doğru görünmeli.
• Custom metadata folder doğru lokal klasöre veya Git repo klasörüne işaret etmeli.
• Application Explorer açılmalı ve AOT nesneleri görünebilmeli.
• Output penceresinde önceki kurulumdan kalan kritik hata bulunmamalı.

UDE’de local development ve cloud execution ayrımı

UDE’nin klasik development VM’den en önemli farkı, geliştirme ve çalışma katmanlarının ayrılmasıdır. Microsoft’un UDE dokümanlarında da bu ayrım development tier ve execution tier olarak ifade edilir. Development tier lokal bilgisayarda metadata ve X++ kaynak kodunu içerir; execution tier ise buluttaki Finance & Operations ortamıdır.

Bu yapı şunu değiştirir: Visual Studio’da oluşturduğumuz model ve X++ nesneleri önce lokal metadata yapısında oluşur. Build işlemi de lokal geliştirme araçlarıyla yapılır. Fakat kodu gerçekten çalıştırmak istediğimizde, ilgili modelin cloud runtime’a deploy edilmesi gerekir.

Bu nedenle UDE üzerinde ilk geliştirme akışını üç parçaya ayırmak faydalı olur:

• Metadata hazırlığı: Model, package, project ve X++ nesnelerinin lokal metadata klasöründe oluşturulması.
• Build kontrolü: Projenin veya modelin lokal geliştirme araçlarıyla derlenmesi ve hataların temizlenmesi.
• Cloud runtime aşaması: Hazırlanan modelin online UDE ortamına deploy edilmesi, çalıştırılması ve debug edilmesi.

Bu yazı ağırlıklı olarak ilk iki parçaya odaklanıyor. Cloud runtime’a deploy ve debug ise serinin devamında daha detaylı ele alınabilir.

Model, package ve project kavramlarını doğru konumlandırmak

Yeni bir geliştirmeye başlamadan önce model, package ve project kavramlarını doğru konumlandırmak gerekir. Bu kavramlar klasik Dynamics AX / Dynamics 365 Finance & Operations geliştirme dünyasından tanıdık olsa da UDE ve Git kullanımıyla birlikte daha dikkatli ele alınmalıdır.

Model nedir?

Model, geliştirdiğimiz metadata ve X++ nesnelerinin mantıksal grubudur. Bir model; table, class, form, menu item, EDT, enum, security artifact gibi nesneleri içerebilir. Model aynı zamanda hangi package içinde yer aldığını, hangi publisher’a ait olduğunu, hangi layer’da konumlandığını ve hangi referanslara ihtiyaç duyduğunu belirler.

Package nedir?

Package, bir veya birden fazla modeli barındırabilen fiziksel ve derlenebilir yapıdır. Genellikle geliştirme ve deployment açısından asıl paketleme birimi package üzerinden düşünülür. Yeni model oluştururken mevcut bir package içine mi ekleneceğine yoksa yeni bir package mı oluşturulacağına karar vermek gerekir.

Project nedir?

Project, Visual Studio içinde üzerinde çalıştığımız model elemanlarını organize ettiğimiz çalışma alanıdır. Operations Project, Finance & Operations geliştirme için kullanılan proje tipidir. Project içindeki elemanlar bir modele bağlıdır. Bu nedenle proje property’lerinde Model alanının doğru seçili olması kritik öneme sahiptir.

Model / package / project ilişkisi

Pratik olarak şöyle düşünebiliriz: Model geliştirme kapsamını, package fiziksel dağıtım ve build sınırını, project ise Visual Studio’daki çalışma organizasyonunu temsil eder. İlk UDE denemelerinde bu üç kavramı sade tutmak, ileride Git ve pipeline süreçlerinde daha kontrollü ilerlemeyi sağlar.

Yeni model oluşturmadan önce isimlendirme kararı

İlk deneme için model adını çok genel seçmemek faydalı olur. Gerçek projelerde model isimleri müşteri, ürün, modül veya geliştirme alanına göre belirlenebilir. UDE denemesi için ise hem kolay anlaşılır hem de ileride Git üzerinde takip edilebilir bir isim seçmek yeterlidir.

Örnek isimler:

• DMRAITest
• DMRCustomizations
• ProjectXCustomizations
• ProjectXIntegration
• ProjectXReports

Bu yazıdaki örneklerde model adı olarak DMRAITest kullanacağım. Siz kendi ortamınızda müşteri veya proje standardınıza uygun bir isim tercih edebilirsiniz.

Visual Studio’da yeni model oluşturma

Visual Studio’da yeni model oluşturmak için Dynamics 365 menüsü altındaki model management araçlarını kullanırız. Visual Studio’yu açtıktan ve doğru UDE metadata configuration’ın aktif olduğundan emin olduktan sonra şu menüye gidilir:

Eğer bu menü görünmüyorsa Finance & Operations Visual Studio extension kurulumu tamamlanmamış olabilir veya Visual Studio yeniden başlatılmamış olabilir. Bu durumda önce Bölüm 5′teki extension ve metadata configuration adımlarını tekrar kontrol etmek gerekir.

Model parametreleri

Create model wizard açıldığında model için bazı temel bilgiler istenir. Bu bilgiler modelin kimliğini ve nasıl organize edileceğini belirler.

Yeni package mı, mevcut package mı?

Model oluşturma adımında en önemli kararlardan biri modelin yeni bir package içinde mi oluşturulacağı yoksa mevcut bir package içine mi ekleneceğidir.

İlk UDE denemesinde ve yeni başlayan bir geliştirme setinde genellikle yeni package oluşturmak daha temiz bir yaklaşımdır. Böylece modelin fiziksel sınırı, build kapsamı ve Git repository yapısı daha net olur.

Mevcut bir projede ise daha önce belirlenmiş package stratejisi varsa yeni model aynı package içine alınabilir. Ancak burada dikkat edilmesi gereken nokta, package bazlı bağımlılıkların ve deployment kapsamının doğru yönetilmesidir.

• Yeni ve bağımsız bir geliştirme alanı için yeni package daha temiz olabilir.
• Mevcut müşteri custom package yapısı varsa aynı package içine yeni model eklemek tercih edilebilir.
• ISV veya ürün geliştirme senaryolarında package sınırı ayrıca tasarlanmalıdır.
• Pipeline ve deployment stratejisi package kararını etkiler.

Referenced packages seçimi

Model oluştururken referans verilecek package’lar seçilir. Bu seçim, yeni modelin hangi mevcut metadata ve kod bileşenlerini kullanabileceğini belirler.

Basit bir runnable class örneği için çoğu durumda Application Platform ve Application Foundation referansları yeterli olabilir. Daha ileri senaryolarda Application Suite veya başka ISV / custom package referansları gerekebilir.

Burada gereksiz referans eklememek önemlidir. Her referans, modelin bağımlılıklarını artırır. Özellikle büyük projelerde gereksiz bağımlılıklar build süresini, deployment kapsamını ve bakım maliyetini artırabilir.

Model oluşturulduktan sonra kontrol

Wizard tamamlandığında Visual Studio yeni model ve package yapısını oluşturur. Bu noktada hemen geliştirmeye başlamadan önce birkaç kısa kontrol yapmak faydalıdır.

• Model oluşturma işlemi hatasız tamamlandı mı?
• Output penceresinde hata veya uyarı var mı?
• Custom metadata folder altında yeni package klasörü oluştu mu?
• Application Explorer içinde model view açıldığında yeni model görünüyor mu?
• Modelin referenced packages bilgisi beklenen şekilde mi?

Application Explorer’da AOT köküne sağ tıklayıp Model view seçeneğini kullanmak, yeni modelin görünürlüğünü kontrol etmek için pratik bir yöntemdir.

Operations Project oluşturma

Model oluşturulduktan sonra Visual Studio içinde bir Operations Project oluşturarak geliştirme yapacağımız çalışma alanını hazırlamamız gerekir. Application Explorer nesneleri görmek ve var olan nesneleri incelemek için kullanılır; yeni nesne oluşturma, düzenleme ve build işlemleri ise bir Finance & Operations project üzerinden yapılır.

Yeni project oluşturmak için şu adımlar izlenebilir:

• Visual Studio’da File > New > Project menüsüne gidilir.
• Project template listesinde Finance and Operations / Dynamics 365 kategorisi seçilir.
• Operations Project template’i seçilir.
• Project için anlamlı bir isim verilir. Örneğin DMRAITestProject.
• Project’in lokasyonu Git repo yapısına uygun bir klasör olarak belirlenir.
• Create seçeneğiyle project oluşturulur.

Project oluşturulduktan sonra Solution Explorer içinde project görünür. Bu aşamada project properties ekranından model ilişkisinin doğru olduğunu kontrol etmek gerekir.

Project properties içinde özellikle Model alanı önemlidir. Bu alan, project içindeki yeni elemanların hangi modele ait olacağını belirler. Yanlış model seçilirse yeni oluşturulan class, table veya diğer nesneler beklenen model yerine başka bir modele yazılabilir.

İlk X++ nesnesi: Runnable class

İlk deneme için table veya form yerine runnable class oluşturmak daha güvenli bir başlangıçtır. Çünkü table oluşturduğumuzda database synchronization konusu devreye girer. Form geliştirdiğimizde ise menu item, security ve çalıştırma senaryosu gibi ek adımlar gerekebilir.

Runnable class ise küçük bir X++ kodunu derlemek, deploy etmek ve debug etmek için iyi bir başlangıç örneğidir. Bu yazıda çok basit bir class oluşturup Infolog’a mesaj yazdıracağız.

Project üzerinde sağ tıklayarak yeni item ekleyelim:

Açılan ekranda Dynamics 365 items altında Code kategorisinden Runnable Class seçilir. Class adı olarak aşağıdaki örnek kullanılabilir:

Örnek X++ kodu

Visual Studio runnable class template’i oluşturduğunda main metodunu içeren temel class yapısı gelir. Bu örnekte main metoduna sadece basit bir info mesajı ekleyebiliriz. Ayrıca arayüzden test yapabilmek için menuye de bir ekleme yaptım.

Bu örneğin amacı işlevsel olarak büyük bir şey yapmak değil. Asıl amaç, modelin doğru oluşturulduğunu, project’in doğru modele bağlı olduğunu, X++ editor’ün çalıştığını ve build sürecinin hatasız ilerlediğini görmektir.

class DMRRunnableClassTest
{
    /// <summary>
    /// Class entry point. The system will call this method when a designated menu
    /// is selected or when execution starts and this class is set as startup object.
    /// </summary>
    /// <param name = "_args">The specified arguments.</param>
    public static void main(Args _args)
    {
        info("Hello from Dynamics 365 F&O UDE");
    }
}

Project build alma

Class oluşturulduktan sonra ilk yapılması gereken işlem project build almaktır. Build işlemi, X++ kodunun ve metadata’nın doğrulanması için temel kontroldür.

Project build almak için Solution Explorer’da project üzerinde sağ tıklayıp Build seçilebilir veya üst menüden Build seçeneği kullanılabilir:

Build sırasında Visual Studio Output penceresi mutlaka açık olmalıdır. Output penceresi build adımlarını, compile hatalarını, best practice uyarılarını ve varsa metadata validation sorunlarını gösterir.

Build başarıyla tamamlandıktan sonra deployment’ın başarılı olduğunu görsel olarak doğrulamak için menüye bir ekleme yapıldı. Runnable class doğrudan menüde görünemediğinden bu yöntem deployment kontrolü için pratik bir yaklaşım sunmaktadır.

Build sırasında nelere bakılmalı?

Build başarılı olduğunda genellikle Output penceresinde hata bulunmaz ve project build tamamlandı mesajı görülür. Ancak özellikle ilk UDE denemelerinde sadece “başarılı” mesajına değil, uyarılara da bakmak gerekir.

• Class doğru model altında mı oluştu?
• Compile error var mı?
• Metadata validation hatası var mı?
• Referenced package eksikliği nedeniyle hata alınıyor mu?
• Best practice uyarıları var mı?
• Output penceresinde path veya permission kaynaklı hata var mı?
• Build sırasında başka bir build işlemi devam ediyor uyarısı var mı?

Eğer build sırasında eksik referans hatası alınırsa modelin referenced packages seçimi tekrar değerlendirilmelidir. Eğer class beklenen modelde görünmüyorsa project properties içindeki Model alanı kontrol edilmelidir.

Synchronize database on build ayarı

Runnable class örneğinde database synchronization ihtiyacı yoktur. Ancak ilerleyen adımlarda table veya view gibi database yapısını etkileyen nesneler geliştirildiğinde synchronize database konusu gündeme gelir.

Operations Project properties içinde Synchronize database on build ayarı bulunur. Bu ayar açık olduğunda build sonrasında database synchronization işlemi de çalışabilir. Küçük denemelerde faydalı olabilir; ancak büyük projelerde build süresini uzatabileceği için kontrollü kullanılmalıdır.

Bu noktada kod çalışır mı?

Klasik development VM alışkanlığıyla bakarsak, build aldıktan sonra kodun hemen çalışmasını bekleyebiliriz. UDE’de ise durum biraz farklıdır. Kod lokal development tier üzerinde derlenmiştir, fakat çalışma cloud execution tier üzerinde gerçekleşir. Bu nedenle kodu çalıştırmak ve debug etmek için modelin online UDE ortamına deploy edilmesi gerekir.

Visual Studio içinde bunun için Dynamics 365 menüsü altındaki deploy seçeneği kullanılır:

Bu ekranda deploy edilecek package/model seçilir ve işlem buluttaki UDE ortamına gönderilir. Deploy sonrasında runnable class çalıştırılabilir ve debug süreci başlatılabilir.

Ancak bu adımı ayrı bir yazıda daha detaylı ele almak daha doğru olur. Çünkü deploy ve debug tarafında authentication, package seçimi, sembol yükleme, breakpoint davranışı, browser URL yapısı ve runtime üzerindeki test akışı gibi ek konular var.

Uygulamayı açıp menüye geldiğimizde yapılan geliştirmeyi görebiliyoruz.

İlk geliştirme sonrası kontrol listesi

Bu yazıdaki adımlar tamamlandıktan sonra aşağıdaki kontroller yapılabilir:

• Yeni model başarıyla oluşturuldu mu?
• Model doğru package içinde mi?
• Referenced packages doğru seçildi mi?
• Application Explorer içinde model görünüyor mu?
• Operations Project oluşturuldu mu?
• Project doğru modele bağlı mı?
• Runnable class doğru model altında oluştu mu?
• X++ kodu compile ediliyor mu?
• Project build başarılı mı?
• Output penceresinde kritik hata veya uyarı var mı?
• Custom metadata folder içinde dosyalar beklenen yerde mi?
• Git kullanılıyorsa yeni dosyalar doğru şekilde takip ediliyor mu?
• Deploy/debug adımına geçmek için model hazır mı?

Sık yapılan hatalar

Yanlış model altında geliştirme yapmak

Project properties içindeki Model alanı kontrol edilmezse yeni oluşturulan class veya diğer nesneler beklenen model yerine başka bir modele eklenebilir. Bu durum özellikle birden fazla model ile çalışılan ortamlarda çok sık karışıklık oluşturur.

Gereksiz referenced package eklemek

Model oluştururken ihtiyaç olmayan package’lara referans vermek bağımlılıkları artırır. Başlangıçta “nasıl olsa lazım olur” diyerek çok fazla referans eklemek yerine ihtiyaç oldukça kontrollü ilerlemek daha sağlıklı olur.

Package stratejisini düşünmeden model oluşturmak

Modelin yeni package içinde mi yoksa mevcut package içinde mi oluşturulacağı ileride build, deploy ve pipeline süreçlerini etkiler. Bu nedenle gerçek projelerde bu karar ekip standardına göre verilmelidir.

Build başarılı olunca kodun cloud ortamda çalışacağını düşünmek

UDE’de build lokal geliştirme katmanında gerçekleşir. Kodu online UDE runtime üzerinde çalıştırmak için modelin deploy edilmesi gerekir.

Kapanış

Bu yazıda UDE ortamına bağlı Visual Studio üzerinde yeni bir model oluşturmayı, package ve reference seçimlerini, Operations Project hazırlığını ve ilk basit X++ runnable class geliştirmesini ele aldık.

Bölüm 5′te Visual Studio ile UDE ortamı arasındaki bağlantıyı kurmuştuk. Bu yazıda ise artık geliştirme tarafına geçtik. Yeni modelin oluşturulması, project’in doğru modele bağlanması ve ilk build’in alınması UDE’de geliştirme düzeninin temelini oluşturuyor.

Burada en kritik nokta, UDE’nin local development ve cloud execution ayrımını doğru anlamak. Kod lokal bilgisayarda yazılıyor ve build ediliyor; fakat çalıştırma ve debug için online UDE ortamına deploy edilmesi gerekiyor. Bu ayrım klasik development VM modelinden gelen alışkanlıkları değiştiriyor.

Bir sonraki yazıda Azure Devops ve git e değineceğim.