Proje dosyasını anlama
tarafından Jason Lee
Microsoft Build Engine (MSBuild) proje dosyaları, derleme ve dağıtım işleminin merkezinde yer alır. Bu konu, MSBuild ve proje dosyasına kavramsal bir genel bakış ile başlar. Proje dosyalarıyla çalışırken karşılaşabileceğiniz temel bileşenleri açıklar ve gerçek dünya uygulamalarını dağıtmak için proje dosyalarını nasıl kullanabileceğinizi gösteren bir örnekle çalışır.
Öğrenecekleriniz:
- MSBuild'in proje oluşturmak için MSBuild proje dosyalarını kullanma şekli.
- MSBuild,Internet Information Services (IIS) Web Dağıtım Aracı (Web Dağıtımı) gibi dağıtım teknolojileriyle nasıl tümleştirilir?
- Proje dosyasının temel bileşenlerini anlama.
- Karmaşık uygulamalar oluşturmak ve dağıtmak için proje dosyalarını nasıl kullanabilirsiniz?
MSBuild ve Proje Dosyası
Visual Studio'da çözümler oluşturduğunuzda ve derlediğinizde, Visual Studio çözümünüzdeki her projeyi derlemek için MSBuild kullanır. Her Visual Studio projesi, proje türünü yansıtan bir dosya uzantısına (örneğin, C# projesi (.csproj), Visual Basic.NET projesine (.vbproj) veya veritabanı projesine (.dbproj) sahip bir MSBuild proje dosyası içerir. Bir proje oluşturmak için MSBuild'in projeyle ilişkili proje dosyasını işlemesi gerekir. Proje dosyası, eklenecek içerik, platform gereksinimleri, sürüm oluşturma bilgileri, web sunucusu veya veritabanı sunucusu ayarları ve gerçekleştirilmesi gereken görevler gibi projenizi oluşturmak için MSBuild'in ihtiyaç duyduğu tüm bilgileri ve yönergeleri içeren bir XML belgesidir.
MSBuild proje dosyaları MSBuild XML şemasını temel alır ve sonuç olarak derleme işlemi tamamen açık ve saydamdır. Ayrıca, MSBuild altyapısını kullanmak için Visual Studio'yu yüklemeniz gerekmez; MSBuild.exe yürütülebilir dosyası .NET Framework bir parçasıdır ve komut isteminden çalıştırabilirsiniz. Geliştirici olarak, msbuild XML şemasını kullanarak kendi MSBuild proje dosyalarınızı oluşturarak projelerinizin nasıl derlendiğine ve dağıtılacağına ilişkin gelişmiş ve ayrıntılı denetimler uygulayabilirsiniz. Bu özel proje dosyaları, Visual Studio'nın otomatik olarak oluşturduğu proje dosyalarıyla tam olarak aynı şekilde çalışır.
Not
MSBuild proje dosyalarını Team Foundation Server'daki (TFS) Team Build hizmetiyle de kullanabilirsiniz. Örneğin, yeni kod iade edildiğinde test ortamına dağıtımı otomatikleştirmek için sürekli tümleştirme (CI) senaryolarında proje dosyalarını kullanabilirsiniz. Daha fazla bilgi için bkz. Team Foundation Server'ı Otomatik Web Dağıtımı için Yapılandırma.
Proje Dosyası Adlandırma Kuralları
Kendi proje dosyalarınızı oluşturduğunuzda, istediğiniz herhangi bir dosya uzantısını kullanabilirsiniz. Ancak, çözümlerinizi başkalarının anlamasını kolaylaştırmak için şu yaygın kuralları kullanmanız gerekir:
- Projeleri derleyen bir proje dosyası oluştururken .proj uzantısını kullanın.
- Diğer proje dosyalarına aktarmak için yeniden kullanılabilir bir proje dosyası oluştururken .targets uzantısını kullanın. .targets uzantısına sahip dosyalar genellikle hiçbir şey oluşturmaz, yalnızca .proj dosyalarınıza aktarabileceğiniz yönergeler içerir.
Dağıtım Teknolojileri ile Tümleştirme
ASP.NET web uygulamaları ve ASP.NET MVC web uygulamaları gibi Visual Studio 2010'da web uygulaması projeleriyle çalıştıysanız, bu projelerin web uygulamasını paketlemeye ve hedef ortama dağıtmaya yönelik yerleşik desteği içerdiğini anlarsınız. Bu projelerin Özellikler sayfaları, uygulamanızın bileşenlerinin nasıl paketlendiğini ve dağıtıldığını yapılandırmak için kullanabileceğiniz Paketle/Yayımla Web ve Paketle/Yayımla SQL sekmelerini içerir. Bu, Web'i Paketle/Yayımla sekmesini gösterir:
Bu özelliklerin arkasındaki temel teknoloji Web Yayımlama İşlem Hattı (WPP) olarak bilinir. WPP temelde, web uygulamalarınız için eksiksiz bir derleme, paket ve dağıtım süreci sağlamak üzere MSBuild ve Web Dağıtımı'nı bir araya getirir.
İyi haber, web projeleri için özel proje dosyaları oluştururken WPP'nin sağladığı tümleştirme noktalarından yararlanabilmenizdir. Proje dosyanıza, projelerinizi oluşturmanıza, web dağıtım paketleri oluşturmanıza ve bu paketleri tek bir proje dosyası ve tek bir MSBuild çağrısı aracılığıyla uzak sunuculara yüklemenize olanak tanıyan dağıtım yönergelerini ekleyebilirsiniz. Derleme işleminizin bir parçası olarak diğer yürütülebilir dosyaları da çağırabilirsiniz. Örneğin, bir şema dosyasından veritabanı dağıtmak için VSDBCMD.exe komut satırı aracını çalıştırabilirsiniz. Bu konu başlığında, kurumsal dağıtım senaryolarınızın gereksinimlerini karşılamak için bu özelliklerden nasıl yararlanabileceğinizi göreceksiniz.
Not
Web uygulaması dağıtım işleminin nasıl çalıştığı hakkında daha fazla bilgi için bkz. web uygulaması proje dağıtımına genel bakış ASP.NET.
Proje Dosyasının Anatomisi
Derleme işlemine daha ayrıntılı bir şekilde bakmadan önce, bir MSBuild proje dosyasının temel yapısı hakkında bilgi sahibi olmak birkaç dakikanızı alır. Bu bölümde, bir proje dosyasını gözden geçirirken, düzenlerken veya oluştururken karşılaşacağınız daha yaygın öğelere genel bir bakış sağlanır. Özellikle şunları öğreneceksiniz:
- Derleme işleminin değişkenlerini yönetmek için özellikleri kullanma.
- Kod dosyaları gibi derleme işlemine girişleri tanımlamak için öğeleri kullanma.
- Proje dosyasının başka bir yerinde tanımlanan özellikleri ve öğeleri kullanarak MSBuild'e yürütme yönergeleri sağlamak için hedefleri ve görevleri kullanma.
Bu, bir MSBuild proje dosyasındaki temel öğeler arasındaki ilişkiyi gösterir:
Proje Öğesi
Project öğesi, her proje dosyasının kök öğesidir. Project öğesi, proje dosyasının XML şemasını tanımlamaya ek olarak, derleme işlemi için giriş noktalarını belirtmek için öznitelikler içerebilir. Örneğin, Contact Manager örnek çözümündePublish.proj dosyası derlemenin FullPublish adlı hedefi çağırarak başlatılması gerektiğini belirtir.
<Project ToolsVersion="4.0" DefaultTargets="FullPublish"
xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
</Project>
Özellikler ve Koşullar
Projenizin başarıyla derlenmesi ve dağıtılması için genellikle bir proje dosyasının çok sayıda farklı bilgi sağlaması gerekir. Bu bilgi parçaları sunucu adlarını, bağlantı dizelerini, kimlik bilgilerini, derleme yapılandırmalarını, kaynak ve hedef dosya yollarını ve özelleştirmeyi desteklemek için eklemek istediğiniz diğer bilgileri içerebilir. Proje dosyasında özelliklerin bir PropertyGroup öğesi içinde tanımlanması gerekir. MSBuild özellikleri anahtar-değer çiftlerinden oluşur. PropertyGroup öğesinde, öğe adı özellik anahtarını, öğesinin içeriği de özellik değerini tanımlar. Örneğin, statik bir sunucu adı ve bağlantı dizesi depolamak için ServerName ve ConnectionString adlı özellikleri tanımlayabilirsiniz.
<PropertyGroup>
<ServerName>FABRIKAM\TEST1</ServerName>
<ConnectionString>
Data Source=FABRIKAM\TESTDB;InitialCatalog=ContactManager,...
</ConnectionString>
</PropertyGroup>
Özellik değerini almak için $(PropertyName) biçimini kullanın. Örneğin, ServerName özelliğinin değerini almak için şunu yazabilirsiniz:
$(ServerName)
Not
Bu konunun devamında özellik değerlerinin nasıl ve ne zaman kullanılacağına yönelik örnekler göreceksiniz.
Bilgileri bir proje dosyasına statik özellikler olarak eklemek, derleme işlemini yönetmek için her zaman ideal bir yaklaşım değildir. Birçok senaryoda, bilgileri diğer kaynaklardan almak veya kullanıcıyı komut isteminden bilgi sağlama yetkisi vermek isteyeceksiniz. MSBuild, herhangi bir özellik değerini komut satırı parametresi olarak belirtmenize olanak tanır. Örneğin, kullanıcı komut satırından MSBuild.exe çalıştırdığında ServerName için bir değer sağlayabilir.
msbuild.exe Publish.proj /p:ServerName=FABRIKAM\TESTWEB1
Not
MSBuild.exe ile kullanabileceğiniz bağımsız değişkenler ve anahtarlar hakkında daha fazla bilgi için bkz. MSBuild Komut Satırı Başvurusu.
Ortam değişkenlerinin ve yerleşik proje özelliklerinin değerlerini almak için aynı özellik söz dizimini kullanabilirsiniz. Sık kullanılan birçok özellik sizin için tanımlanır ve ilgili parametre adını ekleyerek bunları proje dosyalarınızda kullanabilirsiniz. Örneğin, geçerli proje platformunu (örneğin , x86 veya AnyCpu) almak için proje dosyanıza $(Platform) özellik başvurusu ekleyebilirsiniz. Daha fazla bilgi için bkz . Derleme Komutları ve Özellikleri için Makrolar, Ortak MSBuild Proje Özellikleri ve Ayrılmış Özellikler.
Özellikler genellikle koşullarla birlikte kullanılır. Çoğu MSBuild öğesi, MSBuild'in öğeyi değerlendirmesi gereken ölçütleri belirtmenize olanak tanıyan Condition özniteliğini destekler. Örneğin, şu özellik tanımını göz önünde bulundurun:
<PropertyGroup>
<OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\</OutputRoot>
...
</PropertyGroup>
MSBuild bu özellik tanımını işlediğinde, önce $(OutputRoot) özellik değerinin kullanılabilir olup olmadığını denetler. Özellik değeri boşsa (başka bir deyişle, kullanıcı bu özellik için bir değer vermemişse), koşul true olarak değerlendirilir ve özellik değeri olarak ayarlanır. \Publish\Out. Kullanıcı bu özellik için bir değer sağladıysa, koşul false olarak değerlendirilir ve statik özellik değeri kullanılmaz.
Koşulları belirtebileceğiniz farklı yöntemler hakkında daha fazla bilgi için bkz. MSBuild Koşulları.
Öğeler ve Öğe Grupları
Proje dosyasının önemli rollerinden biri, derleme işlemine girişleri tanımlamaktır. Bu girişler genellikle kod dosyaları, yapılandırma dosyaları, komut dosyaları ve derleme işleminin bir parçası olarak işlemeniz veya kopyalamanız gereken diğer dosyalardır. MSBuild proje şemasında, bu girişler Öğe öğeleriyle temsil edilir. Bir proje dosyasında öğelerin bir ItemGroup öğesi içinde tanımlanması gerekir. Özellik öğeleri gibi, bir Öğe öğesini de istediğiniz gibi adlandırabilirsiniz. Ancak, öğenin temsil ettiği dosyayı veya joker karakteri tanımlamak için bir Include özniteliği belirtmeniz gerekir.
<ItemGroup>
<ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/>
</ItemGroup>
Aynı ada sahip birden çok Öğe öğesi belirterek, etkili bir şekilde adlandırılmış kaynak listesi oluşturacaksınız. Bunu uygulamada görmenin iyi bir yolu, Visual Studio'nun oluşturduğu proje dosyalarından birine göz atmaktır. Örneğin, örnek çözümdeki ContactManager.Mvc.csproj dosyası, her biri aynı adlı birkaç Öğe öğesine sahip çok sayıda öğe grubu içerir.
<ItemGroup>
<Reference Include="Microsoft.CSharp" />
<Reference Include="System.Runtime.Serialization" />
<Reference Include="System.ServiceModel" />
...
</ItemGroup>
<ItemGroup>
<Compile Include="Controllers\AccountController.cs" />
<Compile Include="Controllers\ContactsController.cs" />
<Compile Include="Controllers\HomeController.cs" />
...
</ItemGroup>
<ItemGroup>
<Content Include="Content\Custom.css" />
<Content Include="CreateDatabase.sql" />
<Content Include="DropDatabase.sql" />
...
</ItemGroup>
Bu şekilde, proje dosyası MSBuild'e aynı şekilde işlenmesi gereken dosyaların listesini oluşturmasını bildirir; Başvuru listesi başarılı bir derleme için geçerli olması gereken derlemeleri içerir, Derleme listesi derlenmesi gereken kod dosyalarını içerir ve İçerik listesi de değiştirilmeden kopyalanması gereken kaynakları içerir. Bu konunun ilerleyen bölümlerinde derleme işleminin bu öğelere nasıl başvurup kullandığına bakacağız.
Öğe öğeleri ItemMetadata alt öğelerini de içerebilir. Bunlar kullanıcı tanımlı anahtar-değer çiftleridir ve temelde bu öğeye özgü özellikleri temsil eden özelliklerdir. Örneğin, proje dosyasındaki Derleme öğesi öğelerinin çoğu DependentUpon alt öğelerini içerir.
<Compile Include="Global.asax.cs">
<DependentUpon>Global.asax</DependentUpon>
</Compile>
Not
Kullanıcı tarafından oluşturulan öğe meta verilerine ek olarak, tüm öğelere oluşturma işleminde çeşitli ortak meta veriler atanır. Daha fazla bilgi için bkz . İyi Bilinen Öğe Meta Verileri.
ItemGroup öğelerini kök düzeyindeki Project öğesinde veya belirli Hedef öğelerde oluşturabilirsiniz. ItemGroup öğeleri ayrıca, girişleri proje yapılandırması veya platformu gibi koşullara göre derleme işlemine uyarlamanıza olanak tanıyan Koşul özniteliklerini de destekler.
Hedefler ve Görevler
MSBuild şemasında , Task öğesi tek bir derleme yönergesini (veya görevi) temsil eder. MSBuild çok sayıda önceden tanımlanmış görev içerir. Örnek:
- Kopyala görevi dosyaları yeni bir konuma kopyalar.
- Csc görevi Visual C# derleyicisini çağırır.
- Vbc görevi Visual Basic derleyicisini çağırır.
- Exec görevi belirtilen bir programı çalıştırır.
- İleti görevi günlükçüye bir ileti yazar.
Not
Kullanıma sunulan görevlerin tüm ayrıntıları için bkz. MSBuild Görev Başvurusu. Kendi özel görevlerinizi oluşturma dahil olmak üzere görevler hakkında daha fazla bilgi için bkz. MSBuild Görevleri.
Görevler her zaman Hedef öğeler içinde yer almalıdır. Target öğesi, sıralı olarak yürütülen bir veya daha fazla görev kümesidir ve bir proje dosyası birden çok hedef içerebilir. Bir görevi veya bir görev kümesini çalıştırmak istediğinizde, bunları içeren hedefi çağırırsınız. Örneğin, bir iletiyi günlüğe kaydeden basit bir proje dosyanız olduğunu varsayalım.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
Hedefi belirtmek için /t anahtarını kullanarak komut satırından hedefi çağırabilirsiniz.
msbuild.exe Publish.proj /t:LogMessage
Alternatif olarak, çağırmak istediğiniz hedefleri belirtmek için Project öğesine bir DefaultTargets özniteliği ekleyebilirsiniz.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"
DefaultTargets="FullPublish">
<Target Name="LogMessage">
<Message Text="Hello world!" />
</Target>
</Project>
Bu durumda, hedefi komut satırından belirtmeniz gerekmez. Proje dosyasını belirtmeniz yeterlidir ve MSBuild sizin için FullPublish hedefini çağırır.
msbuild.exe Publish.proj
Hem hedefler hem de görevler Koşul özniteliklerini içerebilir. Bu nedenle, belirli koşullar karşılanırsa hedeflerin tamamını veya tek tek görevleri atlayabilirsiniz.
Genel olarak, yararlı görevler ve hedefler oluşturduğunuzda, proje dosyasının başka bir yerinde tanımladığınız özelliklere ve öğelere başvurmanız gerekir:
- Özellik değeri kullanmak için $(PropertyName) yazın; burada PropertyName, Property öğesinin adı veya parametrenin adıdır.
- Bir öğeyi kullanmak için@ (ItemName) yazın; burada ItemName, Item öğesinin adıdır.
Not
Aynı ada sahip birden çok öğe oluşturursanız bir liste oluşturduğunuzu unutmayın. Buna karşılık, aynı ada sahip birden çok özellik oluşturursanız, sağladığınız son özellik değeri aynı ada sahip önceki özelliklerin üzerine yazar; bir özellik yalnızca tek bir değer içerebilir.
Örneğin, örnek çözümdeki Publish.proj dosyasında BuildProjects hedefini inceleyin.
<Target Name="BuildProjects" Condition=" '$(BuildingInTeamBuild)'!='true' ">
<MSBuild Projects="@(ProjectsToBuild)"
Properties="OutDir=$(OutputRoot);
Configuration=$(Configuration);
DeployOnBuild=true;
DeployTarget=Package"
Targets="Build" />
</Target>
Bu örnekte şu önemli noktaları gözlemleyebilirsiniz:
BuildingInTeamBuild parametresi belirtilirse ve true değerine sahipse, bu hedef içindeki görevlerin hiçbiri yürütülmeyecektir.
Hedef , MSBuild görevinin tek bir örneğini içerir. Bu görev, diğer MSBuild projelerini oluşturmanıza olanak tanır.
ProjectsToBuild öğesi göreve geçirilir. Bu öğe, tümü bir öğe grubu içindeki ProjectsToBuild öğe öğeleri tarafından tanımlanan proje veya çözüm dosyalarının listesini temsil edebilir. Bu durumda , ProjectsToBuild öğesi tek bir çözüm dosyasına başvurur.
<ItemGroup> <ProjectsToBuild Include="$(SourceRoot)ContactManager-WCF.sln"/> </ItemGroup>MSBuild görevine geçirilen özellik değerleri OutputRoot ve Configuration adlı parametreleri içerir. Bunlar, sağlanmışsa parametre değerlerine veya sağlanmıyorsa statik özellik değerlerine ayarlanır.
<PropertyGroup> ... <Configuration Condition=" '$(Configuration)'=='' ">Release </Configuration> <OutputRoot Condition=" '$(OutputRoot)'=='' ">..\Publish\Out\ </OutputRoot> ... </PropertyGroup>
MSBuild görevinin Build adlı bir hedefi çağırdığını da görebilirsiniz. Bu, Visual Studio proje dosyalarında yaygın olarak kullanılan ve Derleme, Temizleme, Yeniden Derleme ve Yayımlama gibi özel proje dosyalarınızda kullanabileceğiniz çeşitli yerleşik hedeflerden biridir. Derleme işlemini denetlemek için hedefleri ve görevleri kullanma ve bu konunun devamında özellikle MSBuild görevi hakkında daha fazla bilgi edineceksiniz.
Not
Hedefler hakkında daha fazla bilgi için bkz. MSBuild Hedefleri.
Proje Dosyalarını Birden Çok Ortamı Destekleyecek Şekilde Bölme
Bir çözümü test sunucuları, hazırlama platformları ve üretim ortamları gibi birden çok ortam için dağıtabilmek istediğinizi varsayalım. Yapılandırma, yalnızca sunucu adları, bağlantı dizeleri vb. açısından değil, aynı zamanda kimlik bilgileri, güvenlik ayarları ve diğer birçok faktör açısından da bu ortamlar arasında önemli ölçüde farklılık gösterebilir. Bunu düzenli olarak yapmanız gerekiyorsa, hedef ortamı her değiştirdiğinizde proje dosyanızda birden çok özelliği düzenlemek gerçekten uygun değildir. Derleme işlemine sonsuz özellik değerlerinin listesinin sağlanmasını gerektirmek de ideal bir çözüm değildir.
Neyse ki bir alternatif var. MSBuild, derleme yapılandırmanızı birden çok proje dosyası arasında bölmenize olanak tanır. Bunun nasıl çalıştığını görmek için örnek çözümde iki özel proje dosyası olduğuna dikkat edin:
- Tüm ortamlar için ortak olan özellikleri, öğeleri ve hedefleri içeren Publish.proj.
- Geliştirici ortamına özgü özellikleri içeren Env-Dev.proj.
Şimdi Publish.proj dosyasının, açılan Project etiketinin hemen altında bir import öğesi içerdiğine dikkat edin.
<Import Project="$(TargetEnvPropsFile)"/>
İçeri Aktar öğesi, başka bir MSBuild proje dosyasının içeriğini geçerli MSBuild proje dosyasına aktarmak için kullanılır. Bu durumda, TargetEnvPropsFile parametresi içeri aktarmak istediğiniz proje dosyasının dosya adını sağlar. MSBuild'i çalıştırdığınızda bu parametre için bir değer sağlayabilirsiniz.
msbuild.exe Publish.proj /p:TargetEnvPropsFile=EnvConfig\Env-Dev.proj
Bu, iki dosyanın içeriğini tek bir proje dosyasında etkili bir şekilde birleştirir. Bu yaklaşımı kullanarak, evrensel derleme yapılandırmanızı içeren bir proje dosyası ve ortama özgü özellikler içeren birden çok ek proje dosyası oluşturabilirsiniz. Sonuç olarak, yalnızca farklı parametre değerine sahip bir komut çalıştırmak çözümünüzü farklı bir ortama dağıtmanıza olanak tanır.
Proje dosyalarınızı bu şekilde bölmek iyi bir uygulamadır. Geliştiricilerin tek bir komut çalıştırarak birden çok ortam için dağıtım yapmasına olanak tanırken, birden çok proje dosyasında evrensel derleme özelliklerinin çoğaltılmasını önler.
Not
Kendi sunucu ortamlarınız için ortama özgü proje dosyalarını özelleştirme yönergeleri için bkz. Hedef Ortam için Dağıtım Özelliklerini Yapılandırma.
Sonuç
Bu konu, MSBuild proje dosyalarına genel bir giriş sağladı ve derleme işlemini denetlemek için kendi özel proje dosyalarınızı nasıl oluşturabileceğinizi açıkladı. Ayrıca proje oluşturma ve birden çok hedefe dağıtmayı kolaylaştırmak için proje dosyalarını evrensel derleme yönergelerine ve ortama özgü derleme özelliklerine bölme kavramını da kullanıma sunulmuştur.
Bir sonraki konu olan Derleme sürecini anlama, gerçekçi bir karmaşıklık düzeyine sahip bir çözümün dağıtımında size yol göstererek derleme ve dağıtımı denetlemek için proje dosyalarını nasıl kullanabileceğiniz hakkında daha fazla içgörü sağlar.
Daha Fazla Bilgi
Proje dosyalarına ve WPP'ye daha ayrıntılı bir giriş için bkz. inside the Microsoft Build Engine: Using MSBuild and Team Foundation Build by Sayed Ibrahim Hashimi and William Bartholomew, ISBN: 978-0-7356-4524-0.
Geri Bildirim
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz. https://aka.ms/ContentUserFeedback.
Gönderin ve geri bildirimi görüntüleyin