MSBuild tulajdonságok

A tulajdonságok név-érték párok, amelyek a buildek konfigurálásához használhatók. A tulajdonságok hasznosak az értékek tevékenységeknek való átadásához, a feltételek kiértékeléséhez és a projektfájlban hivatkozott értékek tárolásához.

Tulajdonságok definiálása és hivatkozása egy projektfájlban

A tulajdonságokat úgy deklarálja a rendszer, hogy létrehoz egy olyan elemet, amely a tulajdonság nevét egy PropertyGroup elem gyermekeként adja meg. Az alábbi XML például létrehoz egy olyan tulajdonságot BuildDir , amelynek értéke a következő Build.

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

Az érvényes tulajdonságnevek nagybetűvel vagy kisbetűs ASCII-betűvel vagy aláhúzásjellel kezdődnek(_); az érvényes további karakterek közé tartoznak az alfanumerikus karakterek (ASCII-betűk vagy számjegyek), az aláhúzásjel és a kötőjel (-).

A projektfájlban a tulajdonságokra a szintaxis $(<PropertyName>)hivatkozik. Az előző példában szereplő tulajdonságra például a rendszer a használatával $(BuildDir)hivatkozik.

A tulajdonságértékek a tulajdonság újradefiniálásával módosíthatók. A BuildDir tulajdonság az alábbi XML-fájl használatával adható meg új értékként:

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

A tulajdonságok kiértékelése abban a sorrendben történik, amelyben azok megjelennek a projektfájlban. Az új értéket a régi érték BuildDir hozzárendelése után kell deklarálni.

Fenntartott tulajdonságok

Az MSBuild fenntart néhány tulajdonságnevet a projektfájlra és az MSBuild bináris fájlokra vonatkozó információk tárolásához. Ezekre a tulajdonságokra a $ jelöléssel hivatkozunk, ugyanúgy, mint bármely más tulajdonságra. A $(MSBuildProjectFile) például a projektfájl teljes fájlnevét adja vissza, beleértve a fájlnévkiterjesztést is.

További információért lásd: Útmutató: Hivatkozás a projektfájl nevére vagy helyére és MSBuild fenntartott és jól ismert tulajdonságok.

MSBuild belső tulajdonságok

Az aláhúzásjellel (_) kezdődő standard importálási fájlokban definiált tulajdonságok privátak az MSBuild számára, és nem olvashatók, nem állíthatók alaphelyzetbe vagy felülbírálhatók a felhasználói kódban.

Környezeti tulajdonságok

A projektfájlok környezeti változóira ugyanúgy hivatkozhat, mint a fenntartott tulajdonságokra. Ha például a környezeti változót szeretné használni a projektfájlban, használja a PATH $(Path) függvényt. Ha a projekt olyan tulajdonságdefiníciót tartalmaz, amelynek neve megegyezik egy környezeti tulajdonság nevével, a projekt tulajdonsága felülírja a környezeti változó értékét.

Minden MSBuild-projektnek elkülönített környezeti blokkja van: csak olvasásokat és írásokat lát a saját blokkjában. Az MSBuild csak akkor olvassa be a környezeti változókat, ha inicializálja a tulajdonsággyűjteményt a projektfájl kiértékelése vagy létrehozása előtt. Ezután a környezeti tulajdonságok statikusak, vagyis minden ívott eszköz ugyanazokkal a névvel és értékekkel kezdődik.

A környezeti változók aktuális értékének lekéréséhez használja a System.Environment.GetEnvironmentVariable tulajdonságfüggvényeket . Az előnyben részesített módszer azonban a tevékenységparaméter EnvironmentVariableshasználata. Az ebben a sztringtömbben beállított környezeti tulajdonságok a rendszer környezeti változóinak befolyásolása nélkül továbbíthatók az ívott eszköznek.

Jótanács

A rendszer nem minden környezeti változót olvas be, hogy kezdeti tulajdonságokká váljon. A rendszer figyelmen kívül hagyja azokat a környezeti változókat, amelyek neve nem érvényes MSBuild tulajdonságnév, például "386".

További információért lásd: Hogyan: Környezeti változók használata a build során.

Beállításjegyzék tulajdonságai

A rendszerregisztrációs adatbázis értékeit a következő szintaxissal olvashatja el, ahol Hive a beállításjegyzék-hive (például HKEY_LOCAL_MACHINE) MyKey a kulcs neve, MySubKey az alkulcs neve és Value az alkulcs értéke.

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

Az alapértelmezett alkulcsérték lekéréséhez hagyja ki a Value.

$(registry:Hive\MyKey\MySubKey)

Ez a beállításjegyzék-érték egy buildtulajdonság inicializálására használható. Ha például létre szeretne hozni egy buildtulajdonságot, amely a Visual Studio webböngésző kezdőlapját jelöli, használja a következő kódot:

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

Figyelmeztetés

Az MSBuild (dotnet build) .NET SDK-verziójában a beállításjegyzék tulajdonságai nem támogatottak.

Tulajdonságok létrehozása a végrehajtás során

A külső Target elemekhez rendelt tulajdonságok a build kiértékelési fázisában vannak hozzárendelve. A következő végrehajtási fázisban a tulajdonságok az alábbiak szerint hozhatók létre vagy módosíthatók:

  • Bármely tevékenység kibocsáthat egy tulajdonságot. Tulajdonság kibocsátásához a Tevékenység elemnek rendelkeznie kell egy attribútummal rendelkező gyermek PropertyName elemmel.

  • A CreateProperty tevékenység kibocsáthat egy tulajdonságot. Ez a használat elavult.

  • Target az elemek tartalmazhatnak PropertyGroup olyan elemeket, amelyek tulajdonságdeklarációkat tartalmazhatnak.

Globális tulajdonságok

Az MSBuild lehetővé teszi tulajdonságok beállítását a parancssorban a -property (vagy -p) kapcsolóval. Ezek a globális tulajdonságértékek felülírják a projektfájlban beállított tulajdonságértékeket. Ez magában foglalja a környezeti tulajdonságokat, de nem tartalmaz fenntartott tulajdonságokat, amelyek nem módosíthatók.

Az alábbi példa a globális Configuration tulajdonságot a következőre DEBUGállítja: .

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

A globális tulajdonságok a többprojektes buildben lévő gyermekprojektekhez is beállíthatók vagy módosíthatók az Properties MSBuild feladat attribútumával. A rendszer a globális tulajdonságokat gyermekprojektekbe is továbbítja, kivéve, ha az RemoveProperties MSBuild feladat attribútuma a nem továbbítandó tulajdonságok listájának megadására szolgál. További információ: MSBuild feladat.

Helyi tulajdonságok

A helyi tulajdonságok alaphelyzetbe állíthatók egy projektben. A globális tulajdonságok nem. Ha egy helyi tulajdonság a parancssorból van beállítva a -p beállítással, a projektfájlban lévő beállítás elsőbbséget élvez a parancssorral szemben.

Egy helyi tulajdonságot a projektcímkében lévő attribútum használatával TreatAsLocalProperty adhat meg.

A következő kód azt határozza meg, hogy két tulajdonság helyi:

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

A rendszer nem továbbítja a helyi tulajdonságokat a többprojektes buildben lévő gyermekprojektek számára. Ha megad egy értéket a parancssorban a -p beállítással, a gyermekprojektek a szülőprojektben módosított helyi érték helyett a globális tulajdonság értékét kapják meg, de a gyermekprojekt (vagy annak bármely importálása) a sajátjával TreatAsLocalPropertyis módosíthatja.

Példa helyi tulajdonságokkal

Az alábbi példakód a következő hatásokat TreatAsLocalPropertymutatja be:

<!-- 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>

Tegyük fel, hogy létrehoz egy test1.proj parancssort, és megadja TreatedAsLocalProperty a globális értéket GlobalOverrideValue:

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

A kimenet a következő:

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

A gyermekprojekt örökli a globális értéket, de a szülőprojekt a helyileg beállított tulajdonságot használja.

Helyi tulajdonságok és importálás

Ha TreatAsLocalProperty attribútumot használ az importált projekthez, a sorrend fontos, ha figyelembe veszi, hogy a tulajdonság milyen értéket kap.

Az alábbi példakód egy importált projektre gyakorolt hatását TreatAsLocalProperty mutatja be:

<!-- 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.props -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

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

Tegyük fel, hogy az alábbiak szerint importer.proj hoz létre TreatedAsLocalProp és állít be egy globális értéket:

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

A kimenet a következő:

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

Tegyük fel, hogy a tulajdonsággal TrySecondOverride a következőre trueépít:

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

A kimenet a következő:

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

A példa azt mutatja, hogy a tulajdonság az importált projekt után helyiként lesz kezelve, ahol az TreatAsLocalProperty attribútumot használták, nem csak az importált fájlban. A tulajdonság értékét a globális felülbírálási érték befolyásolja, de csak a használt importált projekt TreatAsLocalProperty.

További információ: Project elem (MSBuild) és Útmutató: Azonos forrásfájlok létrehozása különböző beállításokkal.

Tulajdonság funkciók

A .NET-keretrendszer 4-es verziójától kezdve tulajdonságfüggvényekkel értékelheti ki az MSBuild-szkripteket. Az MSBuild-feladatok használata nélkül elolvashatja a rendszeridőt, összehasonlíthatja a sztringeket, megfeleltetheti a normál kifejezéseket, és számos más műveletet hajthat végre a buildelési szkriptben.

A sztring (példány) metódusokkal bármilyen tulajdonságértéken működhet, és számos rendszerosztály statikus metódusait hívhatja meg. A buildtulajdonságokat például az alábbiak szerint állíthatja be a mai dátumra.

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

További információ és a tulajdonságfüggvények listája: Tulajdonságfüggvények.

XML tárolása tulajdonságokban

A tulajdonságok tetszőleges XML-fájlokat tartalmazhatnak, amelyek segíthetnek az értékek feladatoknak való átadásában vagy a naplózási információk megjelenítésében. Az alábbi példa a ConfigTemplate tulajdonságot mutatja be, amely XML- és egyéb tulajdonsághivatkozásokat tartalmazó értékkel rendelkezik. Az MSBuild a tulajdonsághivatkozásokat a megfelelő tulajdonságértékek használatával cseréli le. A tulajdonságértékek abban a sorrendben vannak hozzárendelve, amelyben megjelennek. Ezért ebben a példában$(MySupportedVersion)$(MyRequiredVersion), és $(MySafeMode) már meg kellett volna határozni.

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

Kapcsolódó tartalom

  • Last updated on