Udostępnij za pośrednictwem

MSBuild

  • Artykuł

Microsoft Build Engine to platforma do tworzenia aplikacji. Ten aparat, znany również jako MSBuild, udostępnia schemat XML dla pliku projektu, który kontroluje sposób, w jaki platforma kompilacji przetwarza i kompiluje oprogramowanie. Program Visual Studio używa programu MSBuild, ale program MSBuild nie jest zależny od Visual Studio. Wywołując msbuild.exe lub dotnet kompilacji w pliku projektu lub rozwiązania, można organizować 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, .vcxproj i inne) 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ź do pozycji Narzędzia kompilacji dla programu 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 .NET SDK. Polecenie dotnet build kompilacji platformy .NET jest dostępne z zestawem .NET SDK w systemach macOS, Windows lub Linux. Polecenie dotnet build kompilacji platformy .NET jest cienką otoką wersji platformy .NET Core MSBuild.exe. Możesz użyć interfejsu wiersza polecenia platformy .NET Core, który używa programu MSBuild, do kompilowania projektów przeznaczonych dla platformy .NET Core i .NET 5 i nowszych.

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. 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ć oznaczać 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.

Uwaga

Usługa Azure Pipelines umożliwia automatyczne kompilowanie, testowanie i wdrażanie aplikacji. System kompilacji może automatycznie uruchamiać kompilacje, gdy deweloperzy zaewidencjonują kod (na przykład jako część strategii ciągłej integracji) lub zgodnie z harmonogramem (na przykład nocną kompilacją kompilacji testu weryfikacyjnego). 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ą ustawioną na .DebugConfiguration

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ę proj na przykład .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 Dokumentacja wiersza polecenia.

Ważne

Przed pobraniem projektu określ wiarygodność kodu.

W przypadku programów .NET Core i .NET 5 lub nowszych zwykle używa dotnet build się do wywoływania programu MSBuild. Zobacz dotnet build (kompilacja dotnet). Jeśli zainstalujesz tylko zestaw .NET SDK, a nie program Visual Studio lub narzędzia Visual Studio Build Tools, masz program MSBuild tylko za pośrednictwem programu dotnet build.

Wiersz polecenia zawiera listę opcji wiersza polecenia dotnet build --help specyficznych dla dotnet build, a nie wszystkich opcji 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 program , 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 importowanych plików XML MSBuild z rozszerzeniami takimi jak .props i .targets do definiowania standardowej logiki kompilacji. Pliki .props definiują właściwości programu MSBuild, a .targets pliki definiują obiekty docelowe 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. Podczas odwołwania się do zestawu SDK, takiego jak zestaw SDK platformy .NET, import plików .props i .target jest niejawnie określany 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 Condition atrybut w elemecie . Zawartość elementów warunkowych jest ignorowana, chyba że warunek zwróci wartość true. W poniższym przykładzie właściwość jest definiowana, Configuration jeśli jeszcze nie została zdefiniowana.

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

Właściwości można odwoływać się w całym pliku projektu przy użyciu składni $(<PropertyName>). Można na przykład odwołać się do właściwości w poprzednich przykładach przy użyciu poleceń $(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 całym pliku projektu przy użyciu składni @(<ItemType>). Na przykład typ elementu w przykładzie będzie przywoływał się przy użyciu polecenia @(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 Compileelementu , comPilelub dowolną inną odmianę wielkości liter i podaje typ elementu "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 Elementy.

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 ITask interfejs. 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 Kopiowanie, które 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 Informacje o zadaniu.

Zadanie jest wykonywane w pliku projektu MSBuild przez utworzenie elementu, który ma nazwę zadania jako element podrzędny elementu docelowego . 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ść BuildDir właściwości zadeklarowanej we wcześniejszym przykładzie.

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

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

Elementy docelowe

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.

Obiekty docelowe 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, aby można było pominąć całe sekcje procesu kompilacji, jeśli ten cel jest aktualny. Aby uzyskać więcej informacji na temat obiektów docelowych, zobacz Cele.

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.

Wielowersyjność kodu

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.

  • Profil platformy , który jest wstępnie zdefiniowanym podzbiorem platformy docelowej, można kierować do profilu platformy docelowej.

  • Jeśli zostanie wydany dodatek Service Pack dla bieżącej wersji programu .NET Framework, możesz go użyć.

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

Aby uzyskać więcej informacji, zobacz Multitargeting (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 kompilacji, możesz programowo wywołać programową aplikację MSBuild z poziomu aplikacji platformy .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 Korzystanie z interfejsu API MSBuild.

MsBuild to open source

MSBuild to projekt typu open source, który akceptuje współtworzenie użytkowników w repozytorium GitHub MSBuild.

Zobacz też

Nazwa opis
Przewodnik: tworzenie pliku projektu MSBuild od podstaw Pokazuje, jak przyrostowo utworzyć podstawowy plik projektu przy użyciu tylko edytora tekstów.
Przewodnik: Używanie programu 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.
Elementy 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.
Docelowe elementy 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 jednostki kodu wykonywalnego, który może być używany przez program MSBuild do wykonywania niepodzielnych operacji kompilacji.
Warunki Omówienie sposobu używania atrybutu Condition w elemecie MSBuild.
Tworzenie partii Omówienie sposobu kategoryzowania listy elementów przez metadane programu MSBuild do wykonywania w zadaniach i obiektach docelowych.
Wielowersyjność kodu Pokazuje, jak kierować wiele wersji platformy .NET i/lub wielu 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 niestandardowego zadania 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.

Odwołanie