właściwości programu MSBuild

  • Artykuł

Właściwości to pary nazwa-wartość, których można używać do konfigurowania kompilacji. Stanową przydatny mechanizm przekazywania wartości do zadań, obliczania warunków i przechowywania wartości, do których będą prowadziły odwołania z różnych miejsc pliku projektu.

Definiowanie i odwołuje się do właściwości w pliku projektu

Właściwości są deklarowane przez utworzenie elementu, który ma nazwę właściwości jako element podrzędny elementu PropertyGroup . Na przykład następujący kod XML tworzy właściwość o nazwie BuildDir, która ma wartość Build.

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

Prawidłowe nazwy właściwości zaczynają się od wielkiej litery lub małych liter lub podkreślenia (_); prawidłowe kolejne znaki obejmują znaki alfanumeryczne (litery lub cyfry), podkreślenie i łącznik (-).

W całym pliku projektu właściwości są przywołyne przy użyciu składni $(<PropertyName>). Na przykład właściwość w poprzednim przykładzie jest przywołyowana przy użyciu metody $(BuildDir).

Wartości właściwości można zmieniać poprzez zmianę definicji właściwości. Poniższy kod XML pozwala nadać nową wartość właściwości BuildDir:

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

Właściwości są obliczane w kolejności, w jakiej występują w pliku projektu. Nowa wartość właściwości BuildDir musi zostać zadeklarowana po przypisaniu starej wartości.

Właściwości zarezerwowane

Program MSBuild rezerwuje niektóre nazwy właściwości do przechowywania informacji o pliku projektu i plikach binarnych MSBuild. Odwołania do tych właściwości tworzy się przy użyciu notacji $, podobnie jak w przypadku pozostałych właściwości. Na przykład odwołanie $(MSBuildProjectFile) zwraca pełną nazwę pliku projektu, łącznie z rozszerzeniem.

Aby uzyskać więcej informacji, zobacz How to: Reference the name or location of the project file and MSBuild reserved and well-known properties (Jak odwoływać się do nazwy lub lokalizacji pliku projektu) oraz MSBuild reserved i dobrze znanych właściwości.

Właściwości wewnętrzne programu MSBuild

Właściwości zdefiniowane w standardowych plikach importu rozpoczynających się od podkreślenia (_) są prywatne dla programu MSBuild i nie powinny być odczytywane, resetowane ani zastępowane w kodzie użytkownika.

Właściwości środowiska

Odwołania do zmiennych środowiskowych w plikach projektów tworzy się tak samo jako odwołania do właściwości zastrzeżonych. Na przykład aby w pliku projektu użyć zmiennej środowiskowej PATH, należy użyć składni $(Path). Jeśli projekt zawiera definicję właściwości o takiej samej nazwie jak właściwość środowiska, właściwość w projekcie zastępuje wartość zmiennej środowiskowej.

Każdy projekt utworzony w programie MSBuild ma izolowany blok środowiska, tzn. widzi tylko operacje odczytu i zapisu w tym bloku. Program MSBuild odczytuje zmienne środowiskowe tylko podczas inicjowania kolekcji właściwości, przed obliczeniem i skompilowaniem pliku projektu. Wskutek tej operacji właściwości środowiska stają się statyczne, tzn. każde zainicjowane narzędzie na początku używa tych samych nazw i wartości.

Aby uzyskać bieżącą wartość zmiennych środowiskowych z poziomu zduplikowanego narzędzia, użyj funkcji właściwości System.Environment.GetEnvironmentVariable. Jednak preferowaną metodą jest użycie parametru zadania EnvironmentVariables. Właściwości środowiska ustawione w tej tablicy ciągów można przekazywać do zainicjowanego narzędzia bez wpływania na zmienne środowiskowe systemu.

Napiwek

Nie wszystkie zmienne środowiskowe są wczytywane jako właściwości początkowe. Każda zmienna środowiskowa, której nazwa nie jest prawidłową nazwą właściwości MSBuild, taką jak "386", jest ignorowana.

Aby uzyskać więcej informacji, zobacz Instrukcje: używanie zmiennych środowiskowych w kompilacji.

Właściwości rejestru

Wartości rejestru systemu można odczytać przy użyciu następującej składni, gdzie Hive jest gałąź rejestru (na przykład HKEY_LOCAL_MACHINE), MyKey jest nazwą klucza, MySubKey jest nazwą podklucza i Value jest wartością podklucza.

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

Aby odczytać domyślną wartość podklucza, należy pominąć Value.

$(registry:Hive\MyKey\MySubKey)

Ta wartość rejestru może służyć do inicjowania właściwości kompilacji. Na przykład w celu utworzenia właściwości kompilacji reprezentującej stronę główną programu Visual Studio w przeglądarce internetowej, należy użyć następującego kodu:

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

Ostrzeżenie

W wersji zestawu .NET SDK programu MSBuild (dotnet build) właściwości rejestru nie są obsługiwane.

Tworzenie właściwości podczas wykonywania

Właściwościom umieszczonym poza elementami Target wartości są przypisane w fazie obliczania kompilacji. W następnej fazie (wykonywania) właściwości można tworzyć i modyfikować w następujący sposób:

  • Właściwość może być emitowana przez dowolne zadanie. Aby emitować właściwość, element Task musi mieć podrzędny element wyjściowy , który ma PropertyName atrybut.

  • Właściwość może być emitowana przez zadanie CreateProperty . Takie użycie jest przestarzałe.

  • Target elementy mogą zawierać PropertyGroup elementy, które mogą zawierać deklaracje właściwości.

Właściwości globalne

Program MSBuild umożliwia ustawianie właściwości w wierszu polecenia przy użyciu przełącznika -property (lub -p). Te globalne wartości właściwości zastępują wartości właściwości ustawione w pliku projektu. Dotyczy to również właściwości środowiska, natomiast nie obejmuje właściwości zastrzeżonych, ponieważ nie można ich modyfikować.

W przykładzie poniżej dla globalnej właściwości Configuration jest ustawiana wartość DEBUG.

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

Właściwości globalne można także ustawiać i modyfikować dla projektów podrzędnych w kompilacjach wieloprojektowych. Służy do tego atrybut Properties zadania programu MSBuild. Właściwości globalne są również przekazywane do projektów podrzędnych, chyba że RemoveProperties atrybut zadania MSBuild jest używany do określenia listy właściwości, które nie mają być przekazywane. Aby uzyskać więcej informacji, zobacz ZADANIE MSBuild.

Właściwości lokalne

Właściwości lokalne można zresetować w projekcie. Właściwości globalne nie mogą. Gdy właściwość lokalna jest ustawiana z wiersza polecenia z -p opcją , ustawienie w pliku projektu ma pierwszeństwo przed wierszem polecenia.

Właściwość lokalną należy określić przy użyciu atrybutu TreatAsLocalProperty w tagu projektu.

Poniższy kod określa, że dwie właściwości są lokalne:

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

Właściwości lokalne nie są przekazywane do projektów podrzędnych w kompilacji wieloprojektowej. Jeśli podasz wartość w wierszu polecenia z -p opcją, projekty podrzędne otrzymują wartość właściwości globalnej zamiast wartości lokalnej zmienionej w projekcie nadrzędnym, ale projekt podrzędny (lub dowolny z jego importów) może również zmienić ją na własną wartość TreatAsLocalProperty.

Przykład z właściwościami lokalnymi

W poniższym przykładzie kodu pokazano efekt :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>

Załóżmy, że kompilujesz wiersz polecenia test1.proj i podajesz TreatedAsLocalProperty wartość GlobalOverrideValueglobalną :

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

Wynik jest następujący:

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

Projekt podrzędny dziedziczy wartość globalną, ale projekt nadrzędny używa właściwości zestawu lokalnego.

Właściwości lokalne i importy

Gdy TreatAsLocalProperty atrybut jest używany w importowanym projekcie, kolejność jest ważna podczas rozważania, która wartość pobiera właściwość.

Poniższy przykład kodu przedstawia wpływ TreatAsLocalProperty zaimportowanego projektu:

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

Załóżmy, że tworzysz importer.proj i ustawiasz wartość globalną dla następujących TreatedAsLocalProp wartości:

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

Dane wyjściowe to:

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

Teraz załóżmy, że kompilujesz za pomocą właściwości TrySecondOverride :true

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

Dane wyjściowe to:

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

W przykładzie pokazano, że właściwość jest traktowana jako lokalna po zaimportowaniu projektu, w którym TreatAsLocalProperty użyto atrybutu, a nie tylko w importowanym pliku. Wartość właściwości ma wpływ na wartość globalnego zastąpienia, ale tylko przed importowanym projektem, w którym TreatAsLocalProperty jest używany.

Aby uzyskać więcej informacji, zobacz Project element (MSBuild) i Instrukcje: kompilowanie tych samych plików źródłowych przy użyciu różnych opcji.

Funkcje właściwości

Począwszy od środowiska .NET Framework w wersji 4 do obliczania skryptów programu MSBuild można używać funkcji właściwości. Funkcje umożliwiają odczytywanie godziny systemowej, porównywanie ciągów tekstowych, porównywanie wyrażeń regularnych i wykonywanie wielu innych czynności w skrypcie kompilacji bez używania zadań programu MSBuild.

Można używać metod ciągów tekstowych (wystąpień) do wykonywania operacji na dowolnych wartościach właściwości oraz wywoływać metody statyczne wielu klas systemowych. Na przykład za pomocą poniższej składni można ustawić bieżącą datę we właściwość kompilacji:

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

Aby uzyskać więcej informacji i listę funkcji właściwości, zobacz Funkcje właściwości.

Przechowywanie kodu XML we właściwościach

Właściwości mogą zawierać dowolny kod XML pomocny w przekazywaniu wartości do zadań albo wyświetlaniu informacji o logowaniu. W przykładzie poniżej pokazano właściwość ConfigTemplate, która ma wartość zawierającą kod XML oraz odwołania do innych właściwości. Program MSBuild zastępuje odwołania do właściwości przy użyciu odpowiednich wartości właściwości. Wartości właściwości są przypisywane w kolejności, w jakiej występują. Dlatego w tym przykładzie właściwości użyte w odwołaniach $(MySupportedVersion), $(MyRequiredVersion) i $(MySafeMode) powinny już być zdefiniowane.

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

Powiązana zawartość