Udostępnij za pośrednictwem

MSBuild

  • Artykuł

Microsoft Build Engine to platforma do tworzenia aplikacji. Ten silnik, znany również jako MSBuild, udostępnia schemat XML dla pliku projektu, który kontroluje sposób, w jaki platforma budowania przetwarza i kompiluje oprogramowanie. Program Visual Studio używa programu MSBuild, ale program MSBuild nie zależy od programu Visual Studio. Wywołując msbuild.exe lub dotnet build dla pliku projektu lub rozwiązania, można koordynować i kompilować produkty w środowiskach, w których program Visual Studio nie jest zainstalowany.

Program Visual Studio używa programu MSBuild do ładowania i kompilowania zarządzanych projektów. Pliki projektu w programie Visual Studio (.csproj, .vbproj, .vcxproji innych) zawierają kod XML programu MSBuild wykonywany podczas tworzenia projektu w środowisku IDE. Projekty programu Visual Studio importują wszystkie niezbędne ustawienia i procesy kompilacji, aby wykonywać typowe prace programistyczne, ale można je rozszerzyć lub zmodyfikować z poziomu programu Visual Studio lub za pomocą edytora tekstów.

Aby zainstalować program MSBuild w systemie Windows, który nie ma programu Visual Studio, przejdź na stronę Build Tools for Visual Studio na stronie pobierania . Zainstalowanie programu MSBuild przy użyciu tej metody daje MSBuild.exe.

W przypadku platform .NET Core i .NET 5 lub nowszych inny sposób uzyskiwania odpowiednika programu MSBuild polega na zainstalowaniu zestawu SDK platformy .NET. Polecenie kompilacji platformy .NET dotnet build jest dostępne za pomocą zestawu .NET SDK w systemach macOS, Windows lub Linux. Polecenie kompilacji .NET dotnet build jest cienką osłoną nad wersją .NET Core MSBuild.exe. Do kompilowania projektów przeznaczonych dla .NET Core oraz .NET 5 i nowszych można użyć interfejsu wiersza polecenia (CLI), który korzysta z MSBuild.

Począwszy od programu Visual Studio 2022, podczas kompilowania w programie Visual Studio używana jest 64-bitowa wersja programu MSBuild.

Aby uzyskać informacje o programie MSBuild dla języka C++, zobacz MSBuild (C++).

W poniższych przykładach pokazano, kiedy można uruchamiać kompilacje, wywołując program MSBuild z wiersza polecenia zamiast środowiska IDE programu Visual Studio.

  • Program Visual Studio nie jest zainstalowany.

  • Chcesz użyć 64-bitowej wersji programu MSBuild i używasz programu Visual Studio 2019 lub starszego. Ta wersja programu MSBuild jest zwykle niepotrzebna, ale umożliwia programowi MSBuild dostęp do większej ilości pamięci.

  • Chcesz uruchomić kompilację w wielu procesach jednocześnie. Można jednak użyć środowiska IDE, aby osiągnąć ten sam wynik w projektach w językach C++ i C#.

  • Chcesz zmodyfikować system kompilacji. Na przykład możesz włączyć następujące akcje:

    • Wstępnie przetwarza pliki przed dotarciem do kompilatora.

    • Skopiuj dane wyjściowe kompilacji do innego miejsca.

    • Utwórz skompresowane pliki na podstawie danych wyjściowych kompilacji.

    • Wykonaj krok przetwarzania końcowego. Na przykład możesz chcieć oznaczyć zestaw inną wersją.

Możesz napisać kod w środowisku IDE programu Visual Studio, ale uruchamiać kompilacje przy użyciu programu MSBuild. Innym rozwiązaniem jest kompilowanie kodu w środowisku IDE na komputerze deweloperów, ale uruchomienie programu MSBuild z poziomu wiersza polecenia w celu skompilowania kodu zintegrowanego z repozytorium źródłowego ze współpracy wielu deweloperów.

Notatka

Usługa Azure Pipelines umożliwia automatyczne kompilowanie, testowanie i wdrażanie aplikacji. System kompilacji może automatycznie uruchamiać kompilacje, gdy deweloperzy wprowadzą kod (na przykład jako część strategii ciągłej integracji) lub zgodnie z harmonogramem (na przykład nocnej kompilacji testu weryfikacji kompilacji). Usługa Azure Pipelines kompiluje kod przy użyciu programu MSBuild. Aby uzyskać więcej informacji, zobacz Azure Pipelines.

Aby zapoznać się z samouczkiem wprowadzającym dla programu MSBuild w systemie Windows, zobacz przewodnik : korzystanie z programu MSBuild.

Używanie programu MSBuild w wierszu polecenia

Aby uruchomić program MSBuild w wierszu polecenia, przekaż plik projektu do MSBuild.exe, wraz z odpowiednimi opcjami wiersza polecenia. Opcje wiersza polecenia umożliwiają ustawianie właściwości, wykonywanie określonych obiektów docelowych i ustawianie innych opcji sterujących procesem kompilacji. Na przykład użyj następującej składni wiersza polecenia, aby skompilować plik MyProj.proj z właściwością Configuration ustawioną na Debug.

MSBuild.exe MyProj.proj -property:Configuration=Debug

Program MSBuild nie zmienia swojego zachowania na podstawie rozszerzenia pliku, ale konwencją jest użycie rozszerzeń kończących się na proj, takich jak .csproj, .vcxprojlub .vbproj, dla głównego pliku wejściowego MSBuild, nazywanego "plikiem projektu".

Aby uzyskać więcej informacji na temat opcji wiersza polecenia programu MSBuild, zobacz referencja wiersza polecenia.

Ważny

Przed pobraniem projektu określ wiarygodność kodu.

W przypadku platform .NET Core i .NET 5 lub nowszych zwykle używasz dotnet build do wywoływania programu MSBuild. Zobacz dotnet build. Jeśli instalujesz tylko pakiet .NET SDK, a nie program Visual Studio lub Visual Studio Build Tools, masz program MSBuild tylko za pośrednictwem dotnet build.

Wiersz polecenia dotnet build --help wyświetla opcje wiersza polecenia specyficzne dla dotnet build, a nie wszystkie opcje MSBuild.exe, ale nadal można użyć wszystkich opcji wiersza polecenia wymienionych w dokumentacji wiersza polecenia MSBuild. Opcje, które nie są przetwarzane przez dotnet build, są przekazywane do programu MSBuild.

Plik projektu

Program MSBuild używa formatu pliku projektu opartego na formacie XML, który jest prosty i rozszerzalny. Format pliku projektu MSBuild umożliwia deweloperom opisywanie elementów, które mają zostać skompilowane, a także sposób ich tworzenia dla różnych systemów operacyjnych i konfiguracji. Ponadto format pliku projektu umożliwia deweloperom tworzenie reguł kompilacji wielokrotnego użytku, które mogą być uwzględniane w osobnych plikach, dzięki czemu kompilacje mogą być wykonywane spójnie w różnych projektach w produkcie.

System kompilacji programu Visual Studio przechowuje logikę specyficzną dla projektu w samym pliku projektu i używa zaimportowanych plików XML MSBuild z rozszerzeniami, takimi jak .props i .targets, aby zdefiniować standardową logikę kompilacji. Pliki .props definiują właściwości programu MSBuild, a pliki .targets definiują obiekty docelowe programu MSBuild. Importy te są czasami widoczne w pliku projektu programu Visual Studio, ale w nowszych projektach, takich jak .NET Core, .NET 5 i .NET 6, nie widzisz importów w pliku projektu; Zamiast tego zostanie wyświetlona dokumentacja zestawu SDK, która wygląda następująco:

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

Są to projekty w stylu zestawu SDK. W przypadku odwołwania się do zestawu SDK, takiego jak zestaw SDK platformy .NET, importy plików .props i .target są niejawnie określane przez zestaw SDK.

W poniższych sekcjach opisano niektóre podstawowe elementy formatu pliku projektu MSBuild. Aby zapoznać się z samouczkiem dotyczącym tworzenia podstawowego pliku projektu, zobacz Przewodnik: tworzenie pliku projektu MSBuild od podstaw.

Właściwości

Właściwości reprezentują pary klucz/wartość, których można użyć do konfigurowania kompilacji. 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 poniższy kod tworzy właściwość o nazwie BuildDir, która ma wartość Build.

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

Właściwość można zdefiniować warunkowo, umieszczając atrybut Condition w elemecie . Zawartość elementów warunkowych jest ignorowana, chyba że warunek zwróci wartość true. W poniższym przykładzie właściwość Configuration jest definiowana, jeśli jeszcze nie została zdefiniowana.

<Configuration  Condition=" '$(Configuration)' == '' ">DefaultValue</Configuration>

Właściwości mogą być przywoływane w pliku projektu przy użyciu składni $(<PropertyName>). Na przykład można odwoływać się do właściwości w poprzednich przykładach przy użyciu $(BuildDir) i $(Configuration).

Aby uzyskać więcej informacji o właściwościach, zobacz właściwości programu MSBuild.

Elementy

Elementy są danymi wejściowymi w systemie kompilacji i zwykle reprezentują pliki. Elementy są pogrupowane w typy elementów na podstawie nazw elementów zdefiniowanych przez użytkownika. Te typy elementów mogą służyć jako parametry dla zadań podrzędnych, które używają poszczególnych elementów do wykonywania kroków procesu kompilacji.

Elementy są deklarowane w pliku projektu przez utworzenie elementu, który ma nazwę typu elementu jako element podrzędny elementu ItemGroup. Na przykład poniższy kod tworzy typ elementu o nazwie Compile, który zawiera dwa pliki.

<ItemGroup>
    <Compile Include = "file1.cs"/>
    <Compile Include = "file2.cs"/>
</ItemGroup>

Do typów elementów można odwoływać się w pliku projektu przy użyciu składni @(<ItemType>). Na przykład typ elementu w przykładzie będzie przywoływał się przy użyciu @(Compile).

W programie MSBuild nazwy elementów i atrybutów są uwzględniane wielkości liter. Jednak nazwy właściwości, elementu i metadanych nie są. Poniższy przykład tworzy typ elementu Compile, comPilelub inną wersję i nadaje typowi elementu wartość "one.cs;two.cs".

<ItemGroup>
  <Compile Include="one.cs" />
  <Compile Include="two.cs" />
</ItemGroup>

Elementy można zadeklarować za pomocą symboli wieloznacznych i mogą zawierać dodatkowe metadane dla bardziej zaawansowanych scenariuszy kompilacji. Aby uzyskać więcej informacji na temat elementów, zobacz Items.

Zadania

Zadania to jednostki kodu wykonywalnego używanego przez projekty MSBuild do wykonywania operacji kompilacji. Na przykład zadanie może skompilować pliki wejściowe lub uruchomić narzędzie zewnętrzne. Zadania mogą być ponownie używane i mogą być współużytkowane przez różnych deweloperów w różnych projektach.

Logika wykonywania zadania jest zapisywana w kodzie zarządzanym i mapowana na program MSBuild przy użyciu elementu UsingTask. Możesz napisać własne zadanie, tworząc typ zarządzany, który implementuje interfejs ITask. Aby uzyskać więcej informacji na temat pisania zadań, zobacz Pisanie zadań.

Program MSBuild zawiera typowe zadania, które można modyfikować zgodnie z wymaganiami. Przykłady to copy, który kopiuje pliki, MakeDir, który tworzy katalogi i Csc, który kompiluje pliki kodu źródłowego visual C#. Aby uzyskać listę dostępnych zadań wraz z informacjami o użyciu, zobacz Dokumentacja zadania.

Zadanie jest wykonywane w pliku projektu MSBuild przez utworzenie elementu, który ma nazwę zadania jako element podrzędny elementu Target. Zadania zwykle akceptują parametry, które są przekazywane jako atrybuty elementu. Właściwości i elementy programu MSBuild mogą być używane jako parametry. Na przykład poniższy kod wywołuje zadanie MakeDir i przekazuje mu wartość właściwości BuildDir zadeklarowanej we wcześniejszym przykładzie.

<Target Name="MakeBuildDirectory">
    <MakeDir  Directories="$(BuildDir)" />
</Target>

Aby uzyskać więcej informacji o zadaniach, zobacz Tasks.

Cele

Cele grupują zadania w określonej kolejności i uwidaczniają sekcje pliku projektu jako punkty wejścia w procesie kompilacji. Obiekty docelowe są często grupowane w sekcje logiczne, aby zwiększyć czytelność i umożliwić rozszerzanie. Podzielenie kroków kompilacji na obiekty docelowe umożliwia wywołanie jednego fragmentu procesu kompilacji z innych obiektów docelowych bez kopiowania tej sekcji kodu do każdego obiektu docelowego. Jeśli na przykład kilka punktów wejścia do procesu kompilacji wymaga utworzenia odwołań, możesz utworzyć obiekt docelowy, który kompiluje odwołania, a następnie uruchomić ten element docelowy z każdego punktu wejścia, w którym jest to wymagane.

Cele są deklarowane w pliku projektu przy użyciu elementu Target. Na przykład poniższy kod tworzy element docelowy o nazwie Compile, który następnie wywołuje zadanie Csc zawierające listę elementów zadeklarowaną we wcześniejszym przykładzie.

<Target Name="Compile">
    <Csc Sources="@(Compile)" />
</Target>

W bardziej zaawansowanych scenariuszach obiekty docelowe mogą służyć do opisywania relacji między sobą i przeprowadzania analizy zależności, dzięki czemu można pominąć całe sekcje procesu kompilacji, jeśli ten cel jest up-to-date. Aby uzyskać więcej informacji na temat obiektów docelowych, zobacz Targets.

Dzienniki kompilacji

Możesz rejestrować błędy kompilacji, ostrzeżenia i komunikaty do konsoli lub innego urządzenia wyjściowego. Aby uzyskać więcej informacji, zobacz Uzyskiwanie dzienników kompilacji za pomocą programu MSBuild.

Korzystanie z programu MSBuild w programie Visual Studio

Program Visual Studio używa formatu pliku projektu MSBuild do przechowywania informacji o projektach zarządzanych. Ustawienia projektu, które są dodawane lub zmieniane przy użyciu interfejsu programu Visual Studio, są odzwierciedlane w pliku .*proj, który jest generowany dla każdego projektu. Program Visual Studio używa hostowanego wystąpienia programu MSBuild do kompilowania projektów zarządzanych. Oznacza to, że zarządzany projekt można skompilować w programie Visual Studio lub w wierszu polecenia (nawet jeśli program Visual Studio nie jest zainstalowany), a wyniki będą identyczne.

Aby zapoznać się z samouczkiem dotyczącym korzystania z programu MSBuild w programie Visual Studio, zobacz przewodnik : korzystanie z programu MSBuild.

Wielotargetowanie

Za pomocą programu Visual Studio można skompilować aplikację do uruchomienia w dowolnej z kilku wersji programu .NET Framework lub .NET Core, w tym .NET 5 i nowszych. Na przykład można skompilować aplikację do uruchamiania na platformie .NET Framework 4 na platformie 32-bitowej i skompilować tę samą aplikację do uruchomienia na platformie .NET Framework 4.8 na platformie 64-bitowej. Możliwość kompilowania do więcej niż jednej platformy nosi nazwę multitargeting.

Oto niektóre zalety wielotargetowania:

  • Można tworzyć aplikacje przeznaczone dla wcześniejszych wersji programu .NET Framework, na przykład w wersjach 3.5 i 4.7.2.

  • Możesz określić profil platformy , który jest wstępnie zdefiniowanym podzbiorem platformy docelowej.

  • Jeśli zostanie wydany dodatek Service Pack dla bieżącej wersji programu .NET Framework, możesz na niego skierować swoje działania.

  • Multitargeting gwarantuje, że aplikacja korzysta tylko z funkcji dostępnych w strukturze docelowej i platformie.

Aby uzyskać więcej informacji, zobacz Multitargeting.

Dostosowywanie kompilacji

Program MSBuild zapewnia obsługę szerokiej gamy niestandardowych scenariuszy kompilacji. Większość wbudowanych funkcji można zastąpić lub rozszerzyć. Zobacz Dostosowywanie kompilacji.

Programowe uzyskiwanie dostępu do programu MSBuild

Jeśli tworzysz narzędzie kompilacyjne, możesz programowo wywołać MSBuild z aplikacji .NET. Za pomocą interfejsu API MSBuild można kontrolować cały aspekt złożonego systemu kompilacji. Program MSBuild udostępnia pakiet NuGet z pełnym interfejsem API (przestrzenią nazw Microsoft.Build), którego można używać z poziomu aplikacji .NET do tych celów. Zobacz Użyj interfejsu API MSBuild.

MSBuild jest oprogramowaniem open source

MSBuild to projekt otwartego kodu źródłowego, który przyjmuje wkład użytkowników w repozytorium GitHub MSBuild .

Zobacz też

Tytuł Opis
Przewodnik: tworzenie pliku projektu MSBuild od podstaw Pokazuje, jak przyrostowo utworzyć podstawowy plik projektu przy użyciu tylko edytora tekstów.
Instrukcja : Używanie MSBuild Wprowadza bloki konstrukcyjne programu MSBuild i pokazuje, jak pisać, manipulować i debugować projekty MSBuild bez zamykania środowiska IDE programu Visual Studio.
pojęcia dotyczące programu MSBuild Przedstawia cztery bloki konstrukcyjne programu MSBuild: właściwości, elementy, obiekty docelowe i zadania podrzędne.
elementów Opisuje ogólne pojęcia dotyczące formatu pliku MSBuild i sposób, w jaki elementy pasują do siebie.
właściwości programu MSBuild Wprowadza właściwości i kolekcje właściwości. Właściwości to pary klucz/wartość, których można użyć do konfigurowania kompilacji.
Targets Objaśnienie sposobu grupowania zadań w określonej kolejności i włączania sekcji procesu kompilacji, które mają być wywoływane w wierszu polecenia.
Zadania Przedstawia sposób tworzenia modułu wykonawczego, który może być używany przez program MSBuild do przeprowadzania atomowych operacji kompilacji.
warunki W tym artykule omówiono sposób używania atrybutu Condition w elemecie MSBuild.
Grupowanie Omówienie sposobu, w jaki MSBuild kategoryzuje listy elementów według metadanych dla wykonywania w zadaniach i celach.
wielokierunkowości Pokazuje, jak obsługiwać wiele wersji .NET i/lub wiele platform.
Uzyskiwanie dzienników kompilacji Opisuje sposób rejestrowania zdarzeń kompilacji, komunikatów i błędów.
Jak program MSBuild kompiluje projekty Opisuje wewnętrzny proces kompilacji używany w programie MSBuild
Tworzenie zadania niestandardowego na potrzeby generowania kodu Pokazuje, jak utworzyć zadanie niestandardowe z przykładem kodu.
generowanie klienta interfejsu API REST przy użyciu programu MSBuild Pokazuje, jak rozszerzyć kompilację w celu obsługi generowania klienta interfejsu API REST przy użyciu przykładu kodu.
dodatkowe zasoby Wyświetla listę zasobów społeczności i pomocy technicznej, aby uzyskać więcej informacji na temat programu MSBuild.

Odniesienie

  • dokumentacji programu MSBuild
    Linki do tematów zawierających informacje referencyjne.

  • Słownik
    Definiuje typowe terminy MSBuild.