Свойства MSBuild

Свойства — это пары "имя-значение", которые можно использовать для настройки сборок. Свойства полезны для передачи значений задачам, оценке условий и хранению значений, на которые будут ссылаться в файле проекта.

Определение и ссылка на свойства в файле проекта

Свойства объявляются путем создания элемента, имеющего имя свойства в качестве дочернего элемента PropertyGroup. Например, следующий XML-код создает свойство с именем BuildDir , которое имеет значение Build.

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

Допустимые имена свойств начинаются с буквы или символа подчеркивания в нижнем регистре ASCII(_); допустимые последующие символы включают буквенно-цифровые символы (буквы ИЛИ цифры ASCII), символ подчеркивания и дефиса (-).

В файле проекта свойства ссылаются с помощью синтаксиса $(<PropertyName>). Например, свойство в предыдущем примере ссылается с помощью $(BuildDir).

Значения свойств можно изменить, переопредеив свойство. Свойство BuildDir может быть присвоено новому значению с помощью этого XML-кода:

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

Свойства вычисляются в том порядке, в котором они отображаются в файле проекта. Новое значение BuildDir должно быть объявлено после назначения старого значения.

Зарезервированные свойства

MSBuild резервирует некоторые имена свойств для хранения сведений о файле проекта и двоичных файлах MSBuild. Эти свойства ссылаются с помощью нотации $ так же, как и любое другое свойство. Например, $(MSBuildProjectFile) возвращает полное имя файла проекта, включая расширение имени файла.

Для получения дополнительной информации см. Практическое руководство: как сослаться на имя или расположение файла проекта и зарезервированные и известные свойства MSBuild.

Внутренние свойства MSBuild

Свойства, определенные в стандартных файлах импорта, которые начинаются с подчеркивания (_) являются частными для MSBuild и не должны быть считываются, сбрасываются или переопределяются в пользовательском коде.

Свойства среды

Вы можете ссылаться на переменные среды в файлах проекта так же, как и ссылаться на зарезервированные свойства. Например, чтобы использовать PATH переменную среды в файле проекта, используйте $(Path). Если проект содержит определение свойства, которое имеет то же имя, что и свойство среды, свойство в проекте переопределяет значение переменной среды.

Каждый проект MSBuild имеет изолированный блок среды: он видит только операции чтения и записи в свой собственный блок. MSBuild считывает только переменные среды при инициализации коллекции свойств перед вычислением или сборкой файла проекта. После этого свойства среды являются статическими, то есть каждый из них начинается с одинаковых имен и значений.

Чтобы получить текущее значение переменных среды из разреженного средства, используйте функции property System.Environment.GetEnvironmentVariable. Однако предпочтительный метод — использовать параметр EnvironmentVariablesзадачи. Свойства среды, заданные в этом массиве строк, могут передаваться в средство с разреженной средой, не затрагивая системные переменные среды.

Подсказка

Не все переменные среды считываются, чтобы стать начальными свойствами. Любая переменная среды, имя которой не является допустимым именем свойства MSBuild, например "386", игнорируется.

Дополнительную информацию см. в разделе "Как использовать переменные среды в сборке".

Свойства реестра

Значения системного реестра можно считывать с помощью следующего синтаксиса, где Hive находится куст реестра (например, HKEY_LOCAL_MACHINE), MyKey это имя ключа, MySubKey имя подключа и Value значение подраздела.

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

Чтобы получить значение подключа по умолчанию, опустите значение Value.

$(registry:Hive\MyKey\MySubKey)

Это значение реестра можно использовать для инициализации свойства сборки. Например, чтобы создать свойство сборки, представляющее домашнюю страницу веб-браузера Visual Studio, используйте следующий код:

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

Предупреждение

В версии ПАКЕТА SDK для .NET MSBuild (dotnet build) свойства реестра не поддерживаются.

Создание свойств во время выполнения

Свойства, расположенные вне Target элементов, назначаются значениям во время этапа оценки сборки. На следующем этапе выполнения свойства можно создать или изменить следующим образом:

Свойство может быть вызвано любой задачей. Чтобы выпустить свойство, элемент Task должен иметь дочерний элемент Output , имеющий PropertyName атрибут.
Свойство может быть создано задачей CreateProperty . Это использование устарело.
Target элементы могут содержать элементы, которые могут содержать PropertyGroup объявления свойств.

Глобальные свойства

MSBuild позволяет задать свойства в командной строке с помощью переключателя -property (или -p). Эти глобальные значения свойств переопределяют значения свойств, заданные в файле проекта. Это включает свойства среды, но не включает зарезервированные свойства, которые нельзя изменить.

В следующем примере для глобального Configuration свойства задано значение DEBUG.

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

Глобальные свойства также можно задать или изменить для дочерних проектов в сборке с несколькими проектами с помощью Properties атрибута задачи MSBuild. Глобальные свойства также перенаправляются дочерним проектам, если RemoveProperties атрибут задачи MSBuild не используется для указания списка свойств, которые не следует пересылать. Дополнительные сведения см. в задаче MSBuild.

Локальные свойства

Локальные свойства можно сбросить в проекте. Глобальные свойства не могут. Если локальное свойство задано из командной строки с -p параметром, параметр в файле проекта имеет приоритет над командной строкой.

Вы указываете локальное свойство с помощью атрибута TreatAsLocalProperty в теге проекта.

Следующий код указывает, что два свойства являются локальными:

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

Локальные свойства не перенаправляются дочерним проектам в сборке с несколькими проектами. Если вы предоставляете значение в командной строке с -p параметром, дочерние проекты получают значение глобального свойства вместо локального значения, измененного в родительском проекте, но дочерний проект (или любой из его импортов) также может изменить его собственным TreatAsLocalProperty.

Пример с локальными свойствами

В следующем примере кода показан эффект 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>

Предположим, вы создадите командную строку test1.proj и присвойте TreatedAsLocalProperty глобальному значению GlobalOverrideValue:

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

Выходные данные приведены следующим образом:

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

Дочерний проект наследует глобальное значение, но родительский проект использует локально заданное свойство.

Локальные свойства и импорт

Если TreatAsLocalProperty атрибут используется в импортированном проекте, порядок важен при рассмотрении значения, которое получает свойство.

В следующем примере кода показан эффект TreatAsLocalProperty импортированного проекта:

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

Предположим, что вы создаете importer.proj и задаете глобальное значение TreatedAsLocalProp следующим образом:

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

Результат выглядит так:

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

Теперь предположим, что вы выполняете сборку со свойством TrySecondOverridetrue:

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

Результат выглядит так:

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

В примере показано, что свойство обрабатывается как локальное после импортированного проекта, где TreatAsLocalProperty использовался атрибут, а не только в импортированном файле. Значение свойства влияет на глобальное переопределение, но только перед импортированным проектом, где TreatAsLocalProperty используется.

Дополнительные сведения см. в разделе "Элемент Project" (MSBuild) и практическое руководство. Создание одинаковых исходных файлов с различными параметрами.

Функции свойств

Начиная с .NET Framework версии 4 можно использовать функции свойств для оценки скриптов MSBuild. Системное время, сравнение строк, сопоставление регулярных выражений и выполнение многих других действий в скрипте сборки без использования задач MSBuild.

Вы можете использовать методы строки (экземпляра) для работы с любым значением свойства, и можно вызвать статические методы многих системных классов. Например, можно задать для свойства сборки текущую дату, как показано ниже.

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

Дополнительные сведения и список функций свойств см. в разделе " Функции свойств".

Хранение XML в свойствах

Свойства могут содержать произвольный XML- код, который может помочь в передаче значений задачам или отображению сведений о ведении журнала. В следующем примере показано ConfigTemplate свойство, содержащее значение, содержащее XML и другие ссылки на свойства. MSBuild заменяет ссылки на свойства с помощью соответствующих значений свойств. Значения свойств назначаются в порядке, в котором они отображаются. Таким образом, в этом примере $(MySupportedVersion)$(MyRequiredVersion)и $(MySafeMode) должен быть уже определен.

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-08-08