Wskazówki: używanie programu MSBuild
Program MSBuild jest platformą kompilacji programu Visual Studio firmy Microsoft.Ten przewodnik jest wprowadzeniem do bloków konstrukcyjnych programu MSBuild i pokazuje jak napisać, manipulować i debugować projekty programu MSBuild.Dowiesz się o:
Tworzeniu i manipulowaniu plikiem projektu.
Jak używać właściwości kompilacji.
Jak używać elementów kompilacji.
Program MSBuild można uruchomić za pomocą programu Visual Studio lub w oknie polecenia.Ten przewodnik pokazuje jak utworzyć plik projektu MSBuild przy użyciu programu Visual Studio.Edytowanie pliku projektu możliwe jest w programie Visual Studio, okno polecenia służy do budowania projektu i przeglądania wyników.
Tworzenie projektu programu MSBuild
System projektów programu Visual Studio opiera się na platformie MSBuild.Ułatwia to utworzenie nowego pliku projektu przy użyciu programu Visual Studio.W tej sekcji utworzony zostanie plik projektu Visual C#.Zamiast tego można utworzyć plik projektu w języku Visual Basic.W kontekście tego przewodnika różnica między tymi dwoma plikami projektów jest niewielka.
Aby utworzyć plik projektu
Otwórz program Visual Studio.
W menu Plik, wskaż Nowy, a następnie kliknij przycisk Projekt.
W oknie dialogowym Nowy projekt wybierz typ projektu Visual C#, a następnie wybierz szablon Aplikacja Windows Forms.W polu tekstowym Nazwa, wpisz BuildApp.Uzupełnij pole Lokalizacja dla rozwiązania, na przykład D:\.Zaakceptuj ustawienia domyślne dla Utwórz katalog rozwiązania (zaznaczone), Dodaj do Kontroli Źródła (nie jest zaznaczone), a Nazwa rozwiązania (BuildApp).
Kliknij OK, aby utworzyć plik projektu.
Sprawdzanie pliku projektu.
W poprzedniej sekcji program Visual Studio jest używany do utworzenia pliku projektu programu Visual C#.Plik projektu jest reprezentowany w oknie Eksplorator rozwiązań przez węzeł projektu o nazwie BuildApp.Edytor kodu programu Visual Studio umożliwia zbadanie pliku projektu.
Aby sprawdzić plik projektu
W oknie Eksplorator rozwiązań, kliknij węzeł projektu BuildApp.
W polu Właściwości przeglądarki należy zauważyć, że właściwość Plik projektu jest BuildApp.csproj.Wszystkie pliki projektu posiadają w nazwie przyrostek "proj".Jeśli został utworzony projekt języka Visual Basic, plik projektu ma nazwę BuildApp.vbproj.
Kliknij prawym przyciskiem myszy węzeł projektu, a następnie kliknij przycisk Zwolnij projekt.
Ponownie kliknij prawym przyciskiem myszy węzeł projektu, a następnie kliknij przycisk Edytuj BuildApp.csproj.
Plik projektu pojawi się w edytorze kodu.
Cele i zadania
Pliki projektu są plikami w formacie XML z węzłem głównym Projekt.
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
W elemencie projektu, należy określić obszar nazw xmlns.
Budowanie aplikacji odbywa się za pomocą elementów Element docelowy i Zadanie.
Zadanie jest to najmniejsza jednostka pracy, innymi słowy, "atom" kompilacji.Zadania są niezależnymi składnikami wykonywalnymi, które mogą mieć wejścia i wyjścia.Aktualnie nie ma żadnych zadań, do których jest odwołanie lub które są zdefiniowane w pliku projektu.Dodaj zadania do pliku projektu w poniższych sekcjach.Aby uzyskać więcej informacji, zobacz temat Zadania programu MSBuild.
Element docelowy jest nazwaną sekwencją zadań.Istnieją dwa elementy docelowe na końcu pliku projektu, które aktualnie są ujęte w komentarzach HTML: BeforeBuild i AfterBuild.
<Target Name="BeforeBuild"> </Target> <Target Name="AfterBuild"> </Target>Aby uzyskać więcej informacji, zobacz temat Obiekty docelowe w programie MSBuild.
Węzeł projektu ma opcjonalny atrybut DefaultTargets wybierający domyślny element docelowy do kompilacji, w tym przypadku Build.
<Project ToolsVersion="12.0" DefaultTargets="Build" ...
Element docelowy kompilacji nie jest zdefiniowany w pliku projektu.Zamiast tego są importowane z pliku Microsoft.CSharp.targets za pomocą elementu Import.
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
Importowane pliki są wstawiane do pliku projektu, wszędzie tam, gdzie są one wywoływane.
Program MSBuild śledzi elementy docelowe kompilacji i gwarantuje, że każdy element jest zbudowany nie więcej niż jeden raz.
Dodawanie elementu docelowego i zadania
Dodawanie elementu docelowego do pliku projektu.Należy dodać zadanie do docelowego obiektu, który drukuje komunikat.
Aby dodać element docelowy i zadania
Dodaj wiersze do pliku projektu zaraz po instrukcji Import:
<Target Name="HelloWorld"> </Target>Utworzony zostanie element docelowy o nazwie HelloWorld.Należy zauważyć, że dostępna jest obsługa technologii Intellisense podczas edycji pliku projektu.
Dodaj wiersze do docelowego projektu HelloWorld, tak aby sekcja wynikowa wyglądała następująco:
<Target Name="HelloWorld"> <Message Text="Hello"></Message> <Message Text="World"></Message> </Target>Zapisz plik projektu.
Zadanie wiadomości jest jednym z wielu zadań, które jest dostarczane przez program MSBuild.Aby uzyskać pełną listę dostępnych zadań i informacje dotyczące użycia, zobacz Odwołanie do zadania MSBuild.
Zadanie wiadomości pobiera wartość string atrybutu tekstu jako dane wejściowe i wyświetla je na urządzenie wyjściowe.Docelowy HelloWorld wykonuje zadanie wiadomości dwa razy: po pierwsze, aby wyświetlić "Hello", a następnie aby wyświetlić "World".
Kompilacja elementów docelowych.
Uruchom program MSBuild z wiersza polecenia programu Visual Studio aby skompilować docelowy HelloWorld zdefiniowany powyżej.Użyj przełącznika wiersza polecenia /TARGET lub /t aby wybrać obiekt docelowy.
[!UWAGA]
Występuje tu odniesienie do wiersza polecenia programu Visual Studio jako Okno polecenia w poniższych sekcjach.
Aby skompilować element docelowy.
Kliknij przycisk Start, a następnie kliknij przycisk Wszystkie programy.Zlokalizuj i kliknij wiersz poleceń programu Visual Studio w folderze Visual Studio Tools.
W oknie poleceń przejdź do folderu zawierającego plik projektu, w tym przypadku D:\BuildApp\BuildApp.
Uruchom program msbuild z przełącznika polecenia /t:HelloWorld.Zostanie wybrany i skompilowany element docelowy HelloWorld:
msbuild buildapp.csproj /t:HelloWorldPrzeanalizuj wyjście w Okno poleceń.Powinny zostać wyświetlone dwa wiersze "Hello" i "World":
Hello World
[!UWAGA]
Jeśli zamiast tego zobaczysz The target "HelloWorld" does not exist in the project to prawdopodobnie plik projektu nie został zapisany w edytorze kodu.Zapisz plik i spróbuj ponownie.
Przez zmiany w edytorze kodu i oknie poleceń, można zmieniać plik projektu i szybko przeglądać wyniki.
[!UWAGA]
Jeśli uruchomisz program msbuild bez przełącznika polecenia /t, msbuild utworzy element docelowy dla elementu projektu podany przez atrybut DefaultTarget, w tym przypadku "Build".To spowoduje kompilację aplikacji Windows Forms o nazwie BuildApp.exe.
Właściwości kompilacji
Właściwości kompilacji są parami nazwa-wartość, które prowadzą do kompilacji.Kilka właściwości kompilacji jest już zdefiniowane w górnej części pliku projektu:
<PropertyGroup>
...
<ProductVersion>10.0.11107</ProductVersion>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>{30E3C9D5-FD86-4691-A331-80EA5BA7E571}</ProjectGuid>
<OutputType>WinExe</OutputType>
...
</PropertyGroup>
Wszystkie właściwości są elementami podrzędnymi elementów PropertyGroup.Nazwa właściwości jest nazwą elementu podrzędnego, a wartość właściwości jest elementem tekstu elementu podrzędnego.Na przykład:
<TargetFrameworkVersion>v12.0</TargetFrameworkVersion>
Definiuje właściwości o nazwie TargetFrameworkVersion, nadając jej wartość ciągu "v12.0".
Tworzone właściwości mogą być zmieniane w dowolnym momencie.Jeśli
<TargetFrameworkVersion>v3.5</TargetFrameworkVersion>
pojawia się później w pliku projektu lub w pliku importowanym później do pliku projektu, to wtedy TargetFrameworkVersion przybiera nową wartość "v3.5".
Sprawdzanie wartości właściwości
Aby uzyskać wartość właściwości, należy użyć następującej składni, gdzie PropertyName jest nazwą właściwości:
$(PropertyName)
Składnię tę można stosować do zbadania niektórych właściwości w pliku projektu.
Aby sprawdzić wartość właściwości
W edytorze kodu zamień element docelowy HelloWorld tym kodem:
<Target Name="HelloWorld"> <Message Text="Configuration is $(Configuration)" /> <Message Text="MSBuildToolsPath is $(MSBuildToolsPath)" /> </Target>Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorldZbadaj dane wyjściowe.Powinny zostać wyświetlone następujące dwa wiersze (zależnie od wersji .NET Framework mogą być różnice):
Configuration is Debug MSBuildToolsPath is C:\Program Files\MSBuild\12.0\bin
[!UWAGA]
Jeśli nie widzisz tych wierszy to prawdopodobnie nie został zapisany plik projektu w edytorze kodu.Zapisz plik i spróbuj ponownie.
Właściwości warunkowe
Wiele właściwości, takich jak konfiguracja są zdefiniowane warunkowo, czyli atrybut Condition pojawia się w elemencie właściwości.Właściwości warunkowe są zdefiniowane i określone na nowo tylko wtedy, gdy wyrażenie zwróci wartość "true".Należy zauważyć, że niezdefiniowane właściwości maja podany pusty ciąg jako wartość domyślna.Na przykład:
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
oznacza "Jeśli właściwość konfiguracji nie została jeszcze zdefiniowana, zdefiniuj ją i nadaj jej wartość "Debug"".
Prawie wszystkie elementy programu MSBuild mogą mieć atrybut warunku.Aby uzyskać więcej informacji na temat używania atrybutu warunku, zobacz Warunki MSBuild.
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.MSBuildToolsPath jest przykładem zarezerwowanej właściwości.Odwoływanie się do właściwości zastrzeżonych możliwe jest za pomocą notacji $, podobnie jak do innych właściwości.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.
Zmienne środowiskowe
Można odwołać się do zmiennych środowiskowych w plikach projektu w taki sam sposób, jak do utworzonych właściwości.Na przykład aby użyć zmiennej środowiskowej PATH w pliku projektu, należy użyć $(ścieżka).Jeśli projekt zawiera definicję właściwości, która ma taką samą nazwę jak zmienna środowiskowa, właściwość w projekcie zastępuje wartość zmiennej środowiskowej.Aby uzyskać więcej informacji, zobacz Porady: użycie zmiennych środowiskowych w kompilacji.
Ustawianie właściwości z wiersza polecenia
W wierszu polecenia przy użyciu przełącznika wiersza polecenia /property lub /p można zdefiniować właściwości.Wartości właściwości odebranych z wiersza polecenia zastępują wartości właściwości ustawione w pliku projektu i w zmiennych środowiskowych.
Aby ustawić wartość właściwości z wiersza polecenia
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorld /p:Configuration=ReleaseZbadaj dane wyjściowe.Powinien zostać wyświetlony ten wiersz:
Configuration is Release.
Program MSBuild tworzy właściwość konfiguracji i nadaje jej wartość "Release".
Znaki specjalne
Niektóre znaki mają specjalne znaczenie w plikach projektu programu MSBuild.Przykładami tych znaków są średnik (;) i gwiazdka (*).Aby korzystać z tych znaków specjalnych jako literałów w pliku projektu, muszą one być określone przy użyciu składni % xx, gdzie xx oznacza szesnastkową wartość znaku ASCII.
W celu poprawy czytelności, zmień zadanie Message, tak aby pokazywało wartość właściwości Configuration ze znakami specjalnymi.
Aby używać znaków specjalnych w zadaniu Message
W edytorze kodu zamień oba zadania Message tym wierszem:
<Message Text="%24(Configuration) is %22$(Configuration)%22" />Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorldZbadaj dane wyjściowe.Powinien zostać wyświetlony ten wiersz:
$(Configuration) is "Debug"
Aby uzyskać więcej informacji, zobacz Znaki specjalne w programie MSBuild.
Tworzenie elementów
Element jest fragmentem informacji, zazwyczaj nazwą pliku, która jest używana jako dane wejściowe do kompilacji systemu.Na przykład, aby skompilować kolekcję elementów reprezentujących pliki źródłowe do zestawu, można przekazać ją do zadania o nazwie Compile.
Wszystkie elementy są elementami podrzędnymi elementów ItemGroup.Nazwa elementu jest nazwą elementu podrzędnego, a wartość elementu jest wartością atrybutu Include elementu podrzędnego.Wartości elementów o tej samej nazwie trafiają do typów elementów o tej nazwie. Na przykład:
<ItemGroup>
<Compile Include="Program.cs" />
<Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>
określa grupę elementów zawierających dwa elementy.Typ elementu Compile ma dwie wartości: "Program.cs" i "Properties\AssemblyInfo.cs".
Poniższy kod tworzy ten sam typ elementów, deklarując oba pliki rozdzielone średnikami w jeden atrybut Include.
<ItemGroup>
<Compile Include="Program.cs;Properties\AssemblyInfo.cs" />
</ItemGroup>
Aby uzyskać więcej informacji, zobacz Elementy programu MSBuild.
[!UWAGA]
Ścieżki plików są względne w stosunku do folderu zawierającego plik projektu programu MSBuild.
Sprawdzanie wartości typu elementu
Aby uzyskać wartości typu elementu, należy użyć następującej składni, gdzie ItemType jest nazwą typu elementu:
@(ItemType)
Użyj następującej składni, aby sprawdzić typ elementu Compile w pliku projektu.
Aby sprawdzić wartości typu elementu
W edytorze kodu zamień element docelowy zadania HelloWorld tym kodem:
<Target Name="HelloWorld"> <Message Text="Compile item type contains @(Compile)" /> </Target>Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorldZbadaj dane wyjściowe.Powinna zostać wyświetlona ta linia:
Compile item type contains Form1.cs;Form1.Designer.cs;Program.cs;Properties\AssemblyInfo.cs;Properties\Resources.Designer.cs;Properties\Settings.Designer.cs
Wartości typu elementu są domyślnie rozdzielone średnikami.
Aby zmienić separator typu elementu, należy użyć następującej składni, gdzie ItemType jest typem elementu, a Separator jest ciągiem jednego lub wielu znaków:
@(ItemType, Separator)
Aby użyć znaków powrotu karetki, zmień zadanie Message, aby wyświetlić elementy Compile (jeden na wiersz), zmień wiersz źródła danych (%0A%0D).
Aby wyświetlić wierszami wartości typu elementu,
W edytorze kodu zamień zadanie Message tą linią:
<Message Text="Compile item type contains @(Compile, '%0A%0D')" />Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorld
Zbadaj dane wyjściowe.Powinny zostać wyświetlone następujące wiersze:
Compile item type contains Form1.cs Form1.Designer.cs Program.cs Properties\AssemblyInfo.cs Properties\Resources.Designer.cs Properties\Settings.Designer.cs
Include, Exclude, and Wildcards
Można użyć symboli wieloznacznych "*", "**", i "?" z atrybutem Include, aby dodać elementy do typu elementu.Na przykład:
<Photos Include="images\*.jpeg" />
dodaje wszystkie pliki z rozszerzeniem pliku ".jpeg" z folderu obrazy do typu elementu Photos, podczas gdy
<Photos Include="images\**.jpeg" />
dodaje wszystkie pliki z rozszerzeniem ".jpeg" z folderu obrazy i wszystkich jego podfolderów do typu elementu Photos.Aby uzyskać więcej przykładów, zobacz Porady: wybieranie plików do kompilacji.
Należy zauważyć, że kiedy elementy są deklarowane to są one dodawane do typu elementu.Na przykład:
<Photos Include="images\*.jpeg" />
<Photos Include="images\*.gif" />
tworzy typ elementu o nazwie Photo zawierający wszystkie pliki z folderu obrazy z rozszerzeniem ".jpeg" lub ".gif".Poprzedni wiersz jest równoważny następującemu wyrażeniu:
<Photos Include="images\*.jpeg;images\*.gif" />
Element można wykluczyć z elementu typu atrybutem Exclude.Na przykład:
<Compile Include="*.cs" Exclude="*Designer*">
dodaje wszystkie pliki z rozszerzeniem pliku ".cs" do elementu typu Compile, z wyjątkiem plików, których nazwy zawierają ciąg "Designer".Aby uzyskać więcej przykładów, zobacz Porady: wykluczanie plików z kompilacji.
W elemencie zawierającym zarówno atrybut Include jak też Exclude, atrybut Exclude dotyczy tylko tych składowych, które są dodane także przez atrybut Include.Na przykład:
<Compile Include="*.cs" />
<Compile Include="*.res" Exclude="Form1.cs">
nie wyklucza pliku Form1.cs, który został dodany do poprzedniego elementu.
Aby uwzględnić lub wykluczyć elementy
W edytorze kodu zamień zadanie Message tą linią:
<Message Text="Compile item type contains @(XFiles)" />Dodaj tę grupę elementów zaraz po elemencie Import:
<ItemGroup> <XFiles Include="*.cs;properties/*.resx" Exclude="*Designer*" /> </ItemGroup>Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorldZbadaj dane wyjściowe.Powinien zostać wyświetlony ten wiersz:
Compile item type contains Form1.cs;Program.cs;Properties/Resources.resx
Element metadanych
Elementy mogą zawierać metadane jako uzupełnienie informacji atrybutów Include i Exclude.Metadane służą do zadań, które wymagają więcej informacji na temat elementów niż tylko wartość elementu.
Element metadanych jest zadeklarowany w pliku projektu przez utworzenie elementu podrzędnego o nazwie metadanych.Element może mieć zero lub więcej wartości metadanych.Na przykład następujący element CSFile ma metadane Culture o wartości "Fr":
<ItemGroup>
<CSFile Include="main.cs">
<Culture>Fr</Culture>
</CSFile>
</ItemGroup>
Aby uzyskać wartość metadanych typu elementu, należy użyć następującej składni, gdzie ItemType jest nazwą typu elementu, a MetaDataName to nazwa metadanych:
%(ItemType.MetaDataName)
Aby zbadać metadane elementu
W edytorze kodu zamień zadanie Message tą linią:
<Message Text="Compile.DependentUpon: %(Compile.DependentUpon)" />Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorldZbadaj dane wyjściowe.Powinny zostać wyświetlone następujące wiersze:
Compile.DependentUpon: Compile.DependentUpon: Form1.cs Compile.DependentUpon: Resources.resx Compile.DependentUpon: Settings.settings
Zauważ, jak wyrażenie "Compile.DependentUpon" pojawia się kilka razy.Korzystanie z metadanych z następującej składni w elemencie docelowym powoduje "grupowanie".Grupowanie oznacza, że zadania w obrębie elementu docelowego są wykonane raz dla każdej unikatowej wartości metadanych.To jest skrypt programu MSBuild równoważny popularnej konstrukcji "pętli for".Aby uzyskać więcej informacji, zobacz Przetwarzanie wsadowe w programie MSBuild.
Znane metadane
W każdym przypadku, gdy nowy element jest dodawany do listy elementów, ten element ma przypisywane dobrze znane metadane.Na przykład %(Filename) zwraca nazwę pliku dowolnego elementu.Aby uzyskać pełną listę znanych metadanych, zobacz Metadane dobrze znanego elementu MSBuild.
Aby zbadać znane metadane
W edytorze kodu zamień zadanie Message tą linią:
<Message Text="Compile Filename: %(Compile.Filename)" />Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorldZbadaj dane wyjściowe.Powinny zostać wyświetlone następujące wiersze:
Compile Filename: Form1 Compile Filename: Form1.Designer Compile Filename: Program Compile Filename: AssemblyInfo Compile Filename: Resources.Designer Compile Filename: Settings.Designer
Porównując oba powyższe przykłady, można zobaczyć, że chociaż nie każdy element typu elementu kompilacji ma DependentUpon metadanych, wszystkie elementy mają dobrze znane metadane Filename.
Transformacje metadanych
Listy elementów mogą być przekształcone w nowe listy elementów.Aby przekształcić listy elementów, należy użyć następującej składni, gdzie ItemType jest nazwą typu elementu, a MetadataName to nazwa metadanych:
@(ItemType -> '%(MetadataName)')
Na przykład, lista elementów plików źródłowych może zostać zamieniona na zbiór plików obiektu przy użyciu wyrażeń, takich jak @(SourceFiles -> '%(Filename).obj').Aby uzyskać więcej informacji, zobacz Przekształcenia w programie MSBuild.
Aby przekształcić elementy za pomocą metadanych
W edytorze kodu zamień zadanie Message tą linią:
<Message Text="Backup files: @(Compile->'%(filename).bak')" />Zapisz plik projektu.
W Okno polecenia, wprowadź i wykonaj polecenie:
msbuild buildapp.csproj /t:HelloWorldZbadaj dane wyjściowe.Powinien zostać wyświetlony ten wiersz:
Backup files: Form1.bak;Form1.Designer.bak;Program.bak;AssemblyInfo.bak;Resources.Designer.bak;Settings.Designer.bak
Należy zauważyć, że metadane wyrażone w tej składni nie powodują grupowania.
Co dalej?
Aby dowiedzieć się, jak w kilku krokach utworzyć prosty plik projektu, wypróbuj Wskazówki: tworzenie pliku projektu MSBuild od zera.