Udostępnij za pośrednictwem

Warunki programu MSBuild

  • Artykuł

Program MSBuild obsługuje określony zestaw warunków, które można zastosować wszędzie tam, gdzie dozwolony jest atrybut Condition; zobacz Obsługiwane elementy. W poniższej tabeli opisano te warunki.

Warunek Opis
'stringA' == 'stringB' Daje true, jeśli stringA równa się stringB.

Na przykład:

Condition="'$(Configuration)'=='DEBUG'"

Pojedyncze cudzysłowy nie są wymagane w przypadku prostych ciągów alfanumerycznych ani wartości logicznych. Jednak pojedyncze cudzysłowy są wymagane dla pustych wartości. To sprawdzenie jest niewrażliwe na wielkość liter.
'stringA' != 'stringB' Ocenia true, jeśli stringA nie jest równa stringB.

Na przykład:

Condition="'$(Configuration)'!='DEBUG'"

Pojedyncze cudzysłowy nie są wymagane w przypadku prostych ciągów alfanumerycznych ani wartości logicznych. Jednak pojedyncze cudzysłowy są wymagane dla pustych wartości. To sprawdzenie jest niewrażliwe na wielkość liter.
<, >, <=, >= Oblicza wartości liczbowe operandów. Zwraca true, jeśli ocena relacyjna ma wartość true. Operandy muszą oceniać liczbę dziesiętną lub szesnastkową albo czteroczęściową wersję kropkowaną. Liczby szesnastkowe muszą zaczynać się od 0x. Uwaga: W kodzie XML znaki < i > muszą zostać uniknięte. Symbol < jest reprezentowany jako &lt;. Symbol > jest reprezentowany jako &gt;.
Istnieje("stringA') Ocenia true, jeśli istnieje plik lub folder o nazwie stringA.

Na przykład:

Condition="!Exists('$(Folder)')"

Pojedyncze cudzysłowy nie są wymagane w przypadku prostych ciągów alfanumerycznych ani wartości logicznych. Jednak pojedyncze cudzysłowy są wymagane dla pustych wartości. Ten warunek nie rozszerza symboli wieloznacznych, takich jak *.
HasTrailingSlash("stringA') Daje true, jeśli określony ciąg zawiera ukośnik odwrotny (\) lub ukośnik ukośnik (/).

Na przykład:

Condition="!HasTrailingSlash('$(OutputPath)')"

Pojedyncze cudzysłowy nie są wymagane w przypadku prostych ciągów alfanumerycznych ani wartości logicznych. Jednak pojedyncze cudzysłowy są wymagane dla pustych wartości.
! Daje true, jeśli operand zwróci wartość false.
And Daje true, jeśli oba operandy oceniają wartość true.
Or Daje true, jeśli co najmniej jeden z operandów oblicza wartość true.
() Mechanizm grupowania, który oblicza true, jeśli wyrażenia zawarte wewnątrz funkcji oceny true.
$if$ ( %expression% ), $else$, $endif$ Sprawdza, czy określona %expression% jest zgodna z wartością ciągu przekazanego parametru szablonu niestandardowego. Jeśli warunek $if$ daje true, jego instrukcje są uruchamiane; w przeciwnym razie jest sprawdzany warunek $else$. Jeśli warunek $else$ jest true, jego instrukcje są uruchamiane; w przeciwnym razie warunek $endif$ kończy ocenę wyrażenia.

Aby zapoznać się z przykładami użycia, zobacz logiki parametrów szablonu projektu/elementu programu Visual Studio.

Element Condition jest pojedynczym ciągiem, dlatego wszystkie ciągi, które są używane w wyrażeniu, w tym wokół wartości właściwości, muszą być ujęte w pojedynczy cudzysłów. Odstępy między operatorami są dozwolone i często używane do czytelności, ale nie są wymagane.

Aby użyć operatorów And logicznych i Or, określ operandy wewnątrz wartości ciągu elementu Condition, jak w poniższym przykładzie:

Condition="'$(Configuration)' == 'Debug' And '$(MSBuildProjectExtension)' == '.csproj'"

Operatory logiczne można połączyć w łańcuch. Operator And ma wyższy priorytet niż Or, ale w celu zapewnienia przejrzystości zalecamy używanie nawiasów w przypadku używania wielu operatorów logicznych w celu jawnego określenia kolejności oceny. Jeśli tego nie zrobisz, program MSBuild wyświetla ostrzeżenie MSB4130.

Metody ciągów można używać w warunkach, jak pokazano w poniższym przykładzie, w którym funkcja TrimEnd() jest używana do porównywania tylko odpowiedniej części ciągu, aby odróżnić platformy docelowe .NET Framework i .NET Core.

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net45;net48;netstandard2.1;netcoreapp2.1;netcoreapp3.1</TargetFrameworks>
    </PropertyGroup>

    <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))' == 'net'">
        <!-- Properties for .NET Framework -->
    </PropertyGroup>

</Project>

W plikach projektu MSBuild nie ma prawdziwego typu logicznego. Dane logiczne są reprezentowane we właściwościach, które mogą być puste lub ustawione na dowolną wartość. W związku z tym '$(Prop)' == 'true' oznacza "jeśli prop jest true", ale '$(Prop)' != 'false' oznacza", jeśli prop jest true lub nie ustawiono lub ustawiono coś innego.

Logika logiczna jest obliczana tylko w kontekście warunków, więc ustawienia właściwości, takie jak <Prop2>'$(Prop1)' == 'true'</Prop>, są reprezentowane jako ciąg (po rozszerzeniu zmiennej), nie są oceniane jako wartości logiczne.

Program MSBuild implementuje kilka specjalnych reguł przetwarzania, aby ułatwić pracę z właściwościami ciągów, które są używane jako wartości logiczne. Literały logiczne są akceptowane, więc Condition="true" i Condition="false" działają zgodnie z oczekiwaniami. Program MSBuild zawiera również specjalne reguły do obsługi operatora negacji logicznej. Jeśli więc $(Prop) ma wartość "true", !$(Prop) rozszerza się na !true, a ta wartość jest porównywana z wartością równą false, jak można się spodziewać.

Porównywanie wersji

Operatory relacyjne <, >, <=i >= obsługują wersje analizowane przez System.Version, dzięki czemu można porównać wersje, które mają cztery części liczbowe. Na przykład '1.2.3.4' < '1.10.0.0' jest true.

Ostrożność

System.Version porównania mogą powodować zaskakujące wyniki, gdy jedna lub obie wersje nie określają wszystkich czterech części. Na przykład wersja 1.1 jest starsza niż wersja 1.1.0.

Program MSBuild udostępnia funkcje właściwości do porównywania wersji, które mają inny zestaw reguł zgodnych z semantycznym przechowywaniem wersji (semver).

Rozszerzenia w warunkach

W zależności od pozycji w pliku projektu można użyć rozszerzeń dla właściwości ($), list elementów (@) i metadanych elementów (%). Rozszerzenia zależą od , w jaki sposób program MSBuild przetwarza pliki projektu.

Właściwości

Warunek zawierający wyrażenie, takie jak $(SomeProperty), jest obliczany i konwertowany na wartość właściwości. Jeśli warunek znajduje się poza elementem docelowym, wyrażenie jest obliczane podczas oceny pliku projektu. Wartość właściwości zależy od pozycji w pliku projektu po rozwinięciu wszystkich importów. Jeśli warunek znajduje się w elemecie docelowym, jest obliczany podczas wykonywania obiektu docelowego, a wartość ma wpływ na wszelkie zmiany, które występują podczas wykonywania kompilacji.

Właściwość, która nie jest zdefiniowana w punkcie rozwiniętego pliku projektu, w którym wyrażenie warunku jest obliczane na pusty ciąg bez żadnego błędu diagnostycznego lub ostrzeżenia.

Listy elementów

Warunek zawierający wyrażenie @-, takie jak @(SomeItems), jest rozszerzany w grupach elementów na najwyższym poziomie i w elementach docelowych.

Elementy mogą zależeć od dowolnej właściwości i mogą zależeć od elementów, które są już zdefiniowane w sekwencji.

Przyczyną jest to, że program MSBuild przetwarza pliki projektu w kilku przebiegach. Ocena elementu jest wykonywana po początkowym przeprowadzeniu oceny właściwości i przekazaniu rozszerzenia importu. W związku z tym wyrażenia @-są dozwolone w każdym warunku, który jest obliczany po rozpoczęciu definiowania elementów. Oznacza to, że w elementach, grupach elementów i elementach docelowych.

Metadane

Warunek zawierający wyrażenie metadanych, takie jak %(ItemMetadata), jest rozwinięty w tych samych kontekstach co listy elementów, czyli w grupach elementów na najwyższym poziomie i w elementach docelowych. Jednak rozszerzenie może mieć inne zachowanie w grupie elementów w zależności od tego, czy grupa elementów znajduje się poza elementem docelowym, czy wewnątrz elementu docelowego. Ponadto różne formy wyrażeń metadanych, %(ItemName.MetadataName), %(JustTheMetadataName)i @(ItemName->'%(MetadataName)'), tylko przekształcenie elementu (ostatnie) jest dozwolone poza obiektem docelowym. Wartość %wyrażenie w obiekcie docelowym jest obliczana w czasie wykonywania i zależy od wszelkich zmian stanu podczas wykonywania docelowego. Wykonanie obiektu docelowego i wartości dowolnego %-expressions zawartego w nim jest również zależne od dzielenia na partie obiektu docelowego i może również wyzwalać przetwarzanie wsadowe; zobacz wsadowe MSBuild.

Obsługiwane elementy

Następujące elementy obsługują atrybut Condition:

  • Import
  • ImportGroup
  • Przedmiot
  • ItemDefinitionGroup
  • Grupa elementów
  • ItemMetadata
  • OnError
  • Wyjście
  • Własność
  • PropertyGroup
  • Cel
  • Zadanie
  • UsingTask
  • Kiedy

Zobacz też