Właściwości programu MSBuild

Artykuł
06/10/2015

Właściwości są parami nazwa wartość, których można używać do konfigurowania kompilacji.Właściwości są przydatne do przekazania wartości do zadań, oceny warunków i przechowywania wartości, do których można odwoływać się w całym pliku projektu.

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

Właściwości są zadeklarowane przez tworzenie elementu zawierającego 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>

W całym pliku projektu do właściwości można odwołać się przy użyciu składni $(PropertyName).Na przykład odwołanie do właściwości z poprzedniego przykładu odbywa się przy użyciu $(BuildDir).

Wartości właściwości można zmienić poprzez przedefiniowanie właściwości.Właściwość BuildDir można zastąpić nową wartością za pomocą tego kodu XML:

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

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

Właściwości zastrzeżone

Program MSBuild rezerwuje niektóre nazwy właściwości do przechowywania informacji o pliku projektu i danych binarnych programu MSBuild.Odwołania do tej właściwości odbywają się za pomocą notacji $, podobnie jak w przypadku innych właściwości.Na przykład, $(MSBuildProjectFile) zwraca pełną nazwę pliku dla pliku projektu, łącznie z rozszerzeniem nazwy pliku.

Aby uzyskać więcej informacji, zobacz Porady: odwołanie do nazwy lub lokalizacji pliku projektu i Właściwości MSBuild zarezerwowane i dobrze znane.

Właściwości środowiskowe

Odwołania do zmiennych środowiskowych w plikach projektu odbywają się podobnie, jak odwołania do właściwości zastrzeżonych.Na przykład, aby użyć zmiennej środowiskowej PATH w pliku projektu, należy użyć $(Path).Jeśli projekt zawiera definicję właściwości, która ma taką samą nazwę jak właściwość środowiskowa, właściwość w projekcie zastępuje wartość zmiennej środowiskowej.

Każdy projekt MSBuild ma izolowany blok środowiska: widzi odczyty i zapisy tylko w swoim własnym bloku. MSBuild odczytuje zmienne środowiskowe tylko podczas inicjowania kolekcji właściwości, zanim plik projektu zostanie oszacowany lub skompilowany.Następnie, właściwości środowiskowe są statyczne, oznacza to, że każde pojawiające się narzędzie zaczyna z tymi samymi nazwami i wartościami.

Aby uzyskać bieżące wartości zmiennych środowiskowych w pojawiającym się narzędziu, należy użyć Funkcje właściwości System.Environment.GetEnvironmentVariable.Jednak preferowaną metodą jest użycie parametru zadania EnvironmentVariables.Właściwości środowiska w tej tablicy ciągów mogą być przekazywane do pojawiającego się narzędzia bez wpływu na zmienne środowiskowe systemu.

Porada
Nie wszystkie zmienne środowiskowe są odczytywane, aby stać się właściwościami początkowymi.Wszystkie zmienne środowiskowe, których nazwa jest nieprawidłowymi nazwami właściwości MSBuild, takie jak "386", są ignorowane.

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

Właściwości rejestru

Można odczytać wartości rejestru systemu za pomocą następującej składni, gdzie Hive jest gałęzią rejestru (na przykład HKEY_LOCAL_MACHINE), Key jest nazwą klucza, SubKey jest nazwa podklucza i Value jest wartością podklucza.

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

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

$(registry:Hive\MyKey\MySubKey)

Ta wartość rejestru może być użyta do zainicjowania właściwości kompilacji.Na przykład aby utworzyć właściwość kompilacji, reprezentującą stronę główną przeglądarki sieci Web programu Visual Studio, należy użyć tego kodu:

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

Właściwości globalne

MSBuild pozwala ustawić właściwości w wierszu polecenia za pomocą przełącznika /property (lub /p).Te globalne wartości właściwości zastępują wartości właściwości, które są ustawione w pliku projektu.Zawiera to właściwości środowiska, ale nie zawiera właściwości zastrzeżonych, których nie można zmienić.

Poniższy przykład ustawia globalną właściwość Configuration na DEBUG.

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

Właściwości globalne można także ustawiać lub modyfikować dla projektów podrzędnych w kompilacji wielu projektów, za pomocą atrybutu Properties zadania MSBuild.Aby uzyskać więcej informacji, zobacz Zadanie MSBuild.

Jeśli właściwość jest określona przy użyciu atrybutu TreatAsLocalProperty w znaczniku projektu, wartość właściwości globalnej nie zastępuje wartości właściwość, która jest ustawiona w pliku projektu.Aby uzyskać więcej informacji, zobacz Project — Element (MSBuild) i Porady: kompilacja tych samych plików źródłowych przy użyciu różnych opcji.

Funkcje właściwości

Począwszy od .NET Framework w wersji 4, można użyć funkcji właściwości do oszacowania skryptów MSBuild.Można odczytać czas systemowy, porównywać ciągi znaków, dopasowywać wyrażenia regularne i wykonywać wiele innych działań w skrypcie kompilacji bez korzystania z zadań MSBuild.

Można użyć metod ciągu (wystąpienie) do pracy na wszystkich wartości właściwości i można wywoływać metody statyczne wielu klas systemowych.Na przykład można ustawić właściwość kompilacji na dzisiejszą datę w następujący sposób.

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

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

Tworzenie właściwości podczas wykonywania

Właściwości położone poza elementem Target są przypisanymi wartościami podczas fazy oceny kompilacji.Podczas kolejnej fazy wykonywania, właściwości mogą zostać utworzone lub zmodyfikowane w następujący sposób:

Właściwości mogą być emitowane przez dowolne zadanie.Aby emitować właściwość, element Task musi mieć element podrzędny Output, który ma atrybut PropertyName.
Właściwość może być emitowana przez zadanie CreateProperty.Takie wykorzystanie jest przestarzałe.
Począwszy od .NET Framework 3.5, elementy Target mogą zawierać elementy PropertyGroup, które mogą zawierać deklaracje właściwości.

Przechowywanie XML we właściwościach

Właściwości mogą zawierać dowolny XML, który może pomóc w przekazywaniu wartości do zadań lub wyświetlaniu informacji logowania.W poniższym przykładzie pokazano właściwość ConfigTemplate, która ma wartość, która zawiera XML i inne odwołania właściwości.MSBuild zmienia odwołania właściwości za pomocą ich odpowiednich wartości właściwości.Wartości właściwości są przypisywane w kolejności, w jakiej występują.W związku z tym, w tym przykładzie $(MySupportedVersion), $(MyRequiredVersion) i $(MySafeMode) powinny zostać wcześniej zdefiniowane.

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

Zobacz też

Udostępnij za pośrednictwem