MSBuild-egenskaper

Egenskaper är namn/värde-par som kan användas för att konfigurera versioner. Egenskaper är användbara för att skicka värden till aktiviteter, utvärdera villkor och lagra värden som ska refereras i hela projektfilen.

Definiera och referera till egenskaper i en projektfil

Egenskaper deklareras genom att skapa ett element som har egenskapens namn som ett underordnat element till ett PropertyGroup--element. Följande XML skapar till exempel en egenskap med namnet BuildDir som har värdet Build.

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

Giltiga egenskapsnamn börjar med en versal eller gemen ASCII-bokstav eller understreck (_); giltiga efterföljande tecken inkluderar alfanumeriska tecken (ASCII-bokstäver eller siffror), understreck och bindestreck (-).

I hela projektfilen refereras egenskaper med hjälp av syntaxen $(<PropertyName>). Egenskapen i föregående exempel refereras till till exempel med hjälp $(BuildDir)av .

Egenskapsvärden kan ändras genom att omdefiniera egenskapen. Egenskapen BuildDir kan få ett nytt värde med hjälp av den här XML-koden:

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

Egenskaperna utvärderas i den ordning de visas i projektfilen. Det nya värdet för BuildDir måste deklareras efter att det gamla värdet har tilldelats.

Reserverade egenskaper

MSBuild reserverar vissa egenskapsnamn för att lagra information om projektfilen och MSBuild-binärfilerna. Dessa egenskaper refereras med hjälp av $-notationen, precis som andra egenskaper. Till exempel returnerar $(MSBuildProjectFile) det fullständiga filnamnet för projektfilen, inklusive filnamnstillägget.

Mer information finns i Så refererar du till namnet eller platsen för projektfilen och MSBuild-reserverade och kända egenskaper.

Interna MSBuild-egenskaper

Egenskaper som definieras i standardimportfiler som börjar med ett understreck (_) är privata för MSBuild och bör inte läsas, återställas eller åsidosättas i användarkoden.

Miljöegenskaper

Du kan referera till miljövariabler i projektfiler precis som du refererar till reserverade egenskaper. Om du till exempel vill använda PATH miljövariabeln i projektfilen använder du $(Path). Om projektet innehåller en egenskapsdefinition som har samma namn som en miljöegenskap åsidosätter egenskapen i projektet värdet för miljövariabeln.

Varje MSBuild-projekt har ett isolerat miljöblock: det ser bara läsningar och skrivningar till sitt eget block. MSBuild läser bara miljövariabler när den initierar egenskapssamlingen innan projektfilen utvärderas eller skapas. Efter det är miljöegenskaperna statiska, dvs. varje skapat verktyg börjar med samma namn och värden.

Använd egenskapsfunktionerna System.Environment.GetEnvironmentVariable för att hämta det aktuella värdet för miljövariabler inifrån ett spawned-verktyg. Den bästa metoden är dock att använda aktivitetsparametern EnvironmentVariables. Miljöegenskaper som anges i den här strängmatrisen kan skickas till det skapade verktyget utan att påverka systemmiljövariablerna.

Mer information finns i Så här: Använd miljövariabler i en byggnad.

Registeregenskaper

Du kan läsa systemregistervärden med hjälp av följande syntax, där Hive är registerdatafilen (till exempel HKEY_LOCAL_MACHINE), MyKey är nyckelnamnet, MySubKey är undernyckelns namn och Value är värdet för undernyckeln.

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

Om du vill hämta standardvärdet för undernyckeln utelämnar du Value.

$(registry:Hive\MyKey\MySubKey)

Det här registervärdet kan användas för att initiera en byggegenskap. Om du till exempel vill skapa en byggegenskap som representerar Visual Studio-webbläsarens startsida använder du den här koden:

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

Skapa egenskaper under körning

Egenskaper som placeras utanför Target element tilldelas värden under utvärderingsfasen av en version. Under den efterföljande körningsfasen kan egenskaper skapas eller ändras på följande sätt:

• En egenskap kan genereras av alla aktiviteter. För att generera en egenskap måste aktivitetselementet ha ett underordnat utdataelement som har ett PropertyName attribut.

• En egenskap kan genereras av aktiviteten CreateProperty . Den här användningen är inaktuell.

• Target element kan innehålla PropertyGroup element som kan innehålla egenskapsdeklarationer.

Globala egenskaper

Med MSBuild kan du ange egenskaper på kommandoraden med hjälp av växeln -property (eller -p). Dessa globala egenskapsvärden åsidosätter egenskapsvärden som anges i projektfilen. Detta omfattar miljöegenskaper, men innehåller inte reserverade egenskaper som inte kan ändras.

I följande exempel anges den globala Configuration egenskapen till DEBUG.

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

Globala egenskaper kan också anges eller ändras för underordnade projekt i en flerprojektversion med hjälp Properties av attributet för MSBuild-aktiviteten. Globala egenskaper vidarebefordras också till underordnade projekt om inte RemoveProperties attributet för MSBuild-aktiviteten används för att ange listan över egenskaper som inte ska vidarebefordras. Mer information finns i MSBuild-uppgift.

Lokala egenskaper

Lokala egenskaper kan återställas i ett projekt. Globala egenskaper kan inte. När en lokal egenskap anges från kommandoraden -p med alternativet har inställningen i projektfilen företräde framför kommandoraden.

Du anger en lokal egenskap med hjälp TreatAsLocalProperty av attributet i en projekttagg.

Följande kod anger att två egenskaper är lokala:

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

Lokala egenskaper vidarebefordras inte till underordnade projekt i en flerprojektversion. Om du anger ett värde på kommandoraden -p med alternativet får underordnade projekt värdet för den globala egenskapen i stället för det lokala värdet som ändrats i det överordnade projektet, men det underordnade projektet (eller någon av dess importer) kan också ändra det med sitt eget TreatAsLocalProperty.

Exempel med lokala egenskaper

Följande kodexempel visar effekten av TreatAsLocalProperty:

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

Anta att du skapar kommandoraden test1.proj och ger TreatedAsLocalProperty det globala värdet GlobalOverrideValue:

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

Utdata är följande:

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

Det underordnade projektet ärver det globala värdet, men det överordnade projektet använder den lokalt angivna egenskapen.

Lokala egenskaper och importer

När TreatAsLocalProperty attributet används i importerat projekt är ordningen viktig när du överväger vilket värde egenskapen får.

I följande kodexempel visas effekten av TreatAsLocalProperty på ett importerat projekt:

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

Anta att du skapar importer.proj och anger ett globalt värde för TreatedAsLocalProp på följande sätt:

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

Resultatet är:

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

Anta nu att du skapar med egenskapen TrySecondOverride till true:

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

Resultatet är:

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

Exemplet visar att egenskapen behandlas som lokal efter det importerade projekt där TreatAsLocalProperty attributet användes, inte bara i den importerade filen. Värdet för egenskapen påverkas av det globala åsidosättningsvärdet, men bara före det importerade projekt där TreatAsLocalProperty används.

Mer information finns i Project-elementet (MSBuild) och How to: Build the same source files with different options (Skapa samma källfiler med olika alternativ).

Egenskapsfunktioner

Från och med .NET Framework version 4 kan du använda egenskapsfunktioner för att utvärdera dina MSBuild-skript. Du kan läsa systemtiden, jämföra strängar, matcha reguljära uttryck och utföra många andra åtgärder i byggskriptet utan att använda MSBuild-uppgifter.

Du kan använda strängmetoder (instans) för att arbeta med valfritt egenskapsvärde och du kan anropa statiska metoder för många systemklasser. Du kan till exempel ange en byggegenskap till dagens datum enligt följande.

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

Mer information och en lista över egenskapsfunktioner finns i Egenskapsfunktioner.

Lagra XML i egenskaper

Egenskaper kan innehålla godtycklig XML, vilket kan hjälpa dig att skicka värden till aktiviteter eller visa loggningsinformation. I följande exempel visas egenskapen ConfigTemplate , som har ett värde som innehåller XML och andra egenskapsreferenser. MSBuild ersätter egenskapsreferenserna med hjälp av deras respektive egenskapsvärden. Egenskapsvärden tilldelas i den ordning de visas. I det här exemplet $(MySupportedVersion)bör därför , $(MyRequiredVersion)och $(MySafeMode) redan ha definierats.

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

Relaterat innehåll

• MSBuild-begrepp
• MSBuild
• Anvisningar: Använda miljövariabler i en version
• Anvisningar: Referera till namnet eller platsen för projektfilen
• Gör så här: Skapa samma källfiler med olika alternativ
• reserverade och välkända egenskaper för MSBuild
• Egenskapselement (MSBuild)