MSBuild özellikleri

  • Makale

Özellikler, yapıları yapılandırmak için kullanılabilen ad-değer çiftleridir. Özellikler, değerlerin görevlere geçirilmesinde, koşulların değerlendirilmesinde ve proje dosyası boyunca başvurulacak olan değerlerin depolanmasında yararlıdır.

Proje dosyasında özellikleri tanımlama ve bunlara başvurma

PropertyGroup öğesinin alt öğesi olarak özelliğin adına sahip bir öğe oluşturularak özellikler bildirilir. Örneğin aşağıdaki XML, bir BuildDir değerine sahip olan Build adında bir özellik oluşturur.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

Geçerli özellik adları büyük veya küçük harf veya alt çizgi (_) ile başlar; geçerli sonraki karakterler alfasayısal karakterler (harfler veya basamaklar), alt çizgi ve kısa çizgi (-) içerir.

Proje dosyasının tamamında özelliklere söz dizimi $(<PropertyName>)kullanılarak başvurulur. Örneğin, önceki örnekteki özelliğine kullanılarak $(BuildDir)başvurulur.

Özelliği yeniden tanımlayarak özellik değerlerini değiştirebilirsiniz. Aşağıdaki XML kullanılarak BuildDir özelliğine yeni bir değer verilebilir:

<PropertyGroup>
    <BuildDir>Alternate</BuildDir>
</PropertyGroup>

Özellikler, proje dosyasında göründükleri sırayla değerlendirilir. BuildDir öğesine ait yeni değerin, eski değer atandıktan sonra bildirilmesi gerekir.

Ayrılmış özellikler

MSBuild, proje dosyası ve MSBuild ikili dosyaları hakkındaki bilgileri depolamak için bazı özellik adlarını saklar. Bu özellikler, diğer özelliklere benzer şekilde $ simgesi kullanılarak başvurulur. Örneğin $(MSBuildProjectFile), dosya adı uzantısı dahil olmak üzere proje dosyasının tüm dosya adını döndürür.

Daha fazla bilgi için bkz . Nasıl yapılır: Proje dosyasının adına veya konumuna ve MSBuild ayrılmış ve iyi bilinen özelliklere başvurma.

MSBuild iç özellikleri

Alt çizgi (_) ile başlayan standart içeri aktarma dosyalarında tanımlanan özellikler MSBuild'e özeldir ve kullanıcı kodunda okunmamalı, sıfırlanmamalı veya geçersiz kılınmamalıdır.

Ortam özellikleri

Proje dosyalarındaki ortam değişkenlerine, ayrılmış özelliklere başvurduğunuz şekilde başvurabilirsiniz. Örneğin, proje dosyanızda PATH ortam değişkenini kullanmak için, $(Yol) işaretini kullanın. Proje, ortam özelliği ile aynı ada sahip bir özellik tanımı içeriyorsa projedeki özellik, ortam değişkeninin değerini geçersiz kılar.

Her MSBuild projesi bir yalıtılmış ortam bloğuna sahiptir; yalnızca kendi bloğundaki okumaları ve yazmaları görür. Proje dosyası değerlendirilmeden veya oluşturulmadan önce MSBuild, özellik koleksiyonunu başlattığında yalnızca ortam değişkenlerini okur. Bunun ardından bu ortam özellikleri statiktir, yani her bir araç aynı adlar ve değerler ile başlar.

Oluşturulan bir aracın içinden ortam değişkenlerinin geçerli değerini almak için System.Environment.GetEnvironmentVariable Özellik işlevlerini kullanın. Ancak tercih edilen yöntem, EnvironmentVariables görev parametresinin kullanılmasıdır. Bu dize dizisinde ayarlanan ortam özellikleri, sistem ortamı değişkenlerini etkilemeden oluşturulan araca gönderilebilir.

Bahşiş

Tüm ortam değişkenleri, başlangıç özellikleri olması için okunmaz. Adı "386" gibi geçerli bir MSBuild özellik adı olmayan ortam değişkenleri yoksayılır.

Daha fazla bilgi için bkz . Nasıl yapılır: Derlemede ortam değişkenlerini kullanma.

Kayıt defteri özellikleri

Aşağıdaki söz dizimini kullanarak sistem kayıt defteri değerlerini okuyabilirsiniz; burada Hive kayıt defteri kovanı (örneğin, HKEY_LOCAL_MACHINE), MyKey anahtar adıdır, MySubKey alt anahtar adıdır ve Value alt anahtarın değeridir.

$(registry:Hive\MyKey\MySubKey@Value)

Varsayılan alt anahtar değerini almak için Value öğesini atın.

$(registry:Hive\MyKey\MySubKey)

Bu kayıt defteri değeri, bir yapı özelliğini başlatmak için kullanılabilir. Örneğin, Visual Studio web tarayıcısı giriş sayfasını temsil eden bir yapı özelliği oluşturmak için şu kodu kullanın:

<PropertyGroup>
  <VisualStudioWebBrowserHomePage>
    $(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\14.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

Uyarı

MSBuild ' in .NET SDK sürümünde (dotnet build ), kayıt defteri özellikleri desteklenmez.

Yürütme sırasında özellik oluşturma

Target öğeleri dışında konumlanan özelliklere, bir yapının değerlendirme aşamasında değerler atanır. Sonraki yürütme aşamasında özellikler aşağıdaki şekilde oluşturulabilir veya değiştirilebilir:

  • Bir özellik herhangi bir görev tarafından yayılabilir. Özellik yaymak için Task öğesinin özniteliği olan PropertyName bir alt Output öğesi olmalıdır.

  • Bir özellik CreateProperty görevi tarafından yayılabilir. Bu kullanım önerilmiyor.

  • Target öğeleri, özellik bildirimleri içerebilecek öğeler içerebilir PropertyGroup .

Genel özellikler

MSBuild, -property (veya -p) anahtarını kullanarak komut satırında özellikleri ayarlamanıza olanak tanır. Bu genel özellik değerleri proje dosyasında ayarlanan özellik değerlerini geçersiz kılar. Bu ortam özellikleri içerir, ancak değiştirilemeyen ayrılmış özellikleri içermez.

Aşağıdaki örnek genel Configuration özelliğini DEBUG olarak ayarlar.

msbuild.exe MyProj.proj -p:Configuration=DEBUG

Genel özellikler, MSBuild görevinin Properties özniteliğini kullanarak aynı zamanda çoklu bir proje yapısındaki alt projeler için ayarlanabilir veya değiştirilebilir. Genel özellikler de, iletilmeyecek özellikler listesini belirtmek için MSBuild görevinin özniteliği kullanılmadığı sürece RemoveProperties alt projelere iletilir. Daha fazla bilgi için bkz . MSBuild görevi.

Yerel özellikler

Bir projede yerel özellikler sıfırlanabilir. Genel özellikler yapamaz. Seçeneğiyle -p komut satırından yerel bir özellik ayarlandığında, proje dosyasındaki ayar komut satırından önceliklidir.

Bir proje etiketinde özniteliğini TreatAsLocalProperty kullanarak yerel bir özellik belirtirsiniz.

Aşağıdaki kod, iki özelliğin yerel olduğunu belirtir:

<Project Sdk="Microsoft.Net.Sdk" TreatAsLocalProperty="Prop1;Prop2">

Yerel özellikler, çok projeli bir derlemede alt projelere iletılmaz. Komut satırında seçeneğiyle -p bir değer sağlarsanız, alt projelere üst projede değiştirilen yerel değer yerine genel özelliğin değeri verilir, ancak alt proje (veya içeri aktarmalarından herhangi biri) bunu kendi TreatAsLocalPropertyile de değiştirebilir.

Yerel özelliklere sahip örnek

Aşağıdaki kod örneği, etkisini TreatAsLocalPropertygösterir:

<!-- test1.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>LocalOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <MSBuild Projects="$(MSBuildThisFileDirectory)\test2.proj" Targets="Go2" Properties="Inner=true" />
    </Target>

    <Target Name="Go2" BeforeTargets="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- test2.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <Target Name="Go2">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

test1.proj komut satırı oluşturduğunuzu ve genel değeri GlobalOverrideValueverdiğinizi TreatedAsLocalProperty varsayalım:

dotnet msbuild .\test1.proj -p:TreatedAsLocalProp=GlobalOverrideValue

Çıktı aşağıdaki şekilde olacaktır:

test1.proj(11,9): warning : TreatedAsLocalProp(test): LocalOverrideValue
test2.proj(3,9): warning : TreatedAsLocalProp(test2): GlobalOverrideValue

Alt proje genel değeri devralır, ancak üst proje yerel olarak ayarlanmış özelliğini kullanır.

Yerel özellikler ve içeri aktarmalar

TreatAsLocalProperty İçeri aktarılan projede öznitelik kullanıldığında, özelliğin hangi değeri aldığı dikkate alınırken sıralama önemlidir.

Aşağıdaki kod örneği, içeri aktarılan bir proje üzerindeki etkisini TreatAsLocalProperty gösterir:

<!-- importer.proj -->
<Project>
    <PropertyGroup>
        <TreatedAsLocalProp>FirstOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Import Project="import.props" />

    <PropertyGroup>
        <TreatedAsLocalProp Condition=" '$(TrySecondOverride)' == 'true' ">SecondOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- import.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <!-- Here, TreatedAsLocalProp has the value "ImportOverrideValue"-->
</Project>

için TreatedAsLocalProp aşağıdaki gibi bir genel değer oluşturup importer.proj ayarladığınızı varsayalım:

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue

Çıktı şu olur:

importer.proj(9,9): warning : TreatedAsLocalProp(importer.proj): GlobalOverrideValue

Şimdi özelliğiyle TrySecondOverridetrueoluşturduğunuzu varsayalım:

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue -p:TrySecondOverride=true

Çıktı şu olur:

importer.proj(13,9): warning : TreatedAsLocalProp(importer.proj): SecondOverrideValue

Örnekte özelliğin yalnızca içeri aktarılan dosya içinde değil özniteliğin TreatAsLocalProperty kullanıldığı içeri aktarılan projeden sonra yerel olarak kabul edildiği gösterilmektedir. özelliğinin değeri genel geçersiz kılma değerinden etkilenir, ancak yalnızca kullanılan içeri aktarılan projeden TreatAsLocalProperty önce.

Daha fazla bilgi için bkz . Project öğesi (MSBuild) ve Nasıl yapılır: Farklı seçeneklerle aynı kaynak dosyaları oluşturma.

Özellik işlevleri

.NET Framework sürüm 4'ten başlayarak, MSBuild komut dosyalarınızı değerlendirmek için özellik işlevlerini kullanabilirsiniz. MSBuild görevlerini kullanmadan, yapı komut dosyanızdaki sistem saatini okuyabilir, dizeleri karşılaştırabilir, normal ifadeleri eşleştirebilir ve başka birçok eylemi gerçekleştirebilirsiniz.

Herhangi bir özelliğin üzerinde gerçekleştirmek için dize (örnek) yöntemlerini kullanabilirsiniz ve birçok sistem sınıfının statik yöntemlerini çağırabilirsiniz. Örneğin, bir yapı özelliğini bugünün tarihine aşağıdaki gibi ayarlayabilirsiniz.

<Today>$([System.DateTime]::Now.ToString("yyyy.MM.dd"))</Today>

Daha fazla bilgi ve özellik işlevlerinin listesi için bkz . Özellik işlevleri.

XML'i özelliklerde depolama

Özellikler, değerlerin görevlere geçirilmesini veya günlük bilgilerin görüntülenmesini sağlayabilecek rastgele bir XML içerebilir. Aşağıdaki örnek, XML ve diğer özellik başvurularını içeren bir değere sahip olan ConfigTemplate özelliğini gösterir. MSBuild, ilgili özellik değerlerini kullanarak özellik başvurularının yerini alır. Özellik değerleri göründükleri sırayla atanır. Bu nedenle bu örnekte, $(MySupportedVersion), $(MyRequiredVersion) ve $(MySafeMode) öğelerinin önceden tanımlanmış olması gerekir.

<PropertyGroup>
    <ConfigTemplate>
        <Configuration>
            <Startup>
                <SupportedRuntime
                    ImageVersion="$(MySupportedVersion)"
                    Version="$(MySupportedVersion)"/>
                <RequiredRuntime
                    ImageVersion="$(MyRequiredVersion)"
                    Version="$(MyRequiredVersion)"
                    SafeMode="$(MySafeMode)"/>
            </Startup>
        </Configuration>
    </ConfigTemplate>
</PropertyGroup>

İlgili içerik