Tworzenie pliku projektu MSBuild od podstaw

Artykuł
01/26/2025

Języki programowania przeznaczone dla programu .NET Framework używają plików projektu MSBuild do opisywania i kontrolowania procesu kompilacji aplikacji. Gdy używasz programu Visual Studio do tworzenia pliku projektu MSBuild, odpowiedni kod XML jest dodawany automatycznie do pliku. Warto jednak zrozumieć, jak jest zorganizowany kod XML i jak można go zmienić w celu kontrolowania kompilacji.

Notatka

Ten artykuł jest odpowiedni, jeśli chcesz poznać podstawowe podstawy działania programu MSBuild niezależnie od dowolnego zestawu SDK. Kompilowanie przy użyciu zestawu SDK, takiego jak użycie dotnet build lub dodanie atrybutu Sdk do głównego elementu projektu, nie zostało omówione w tym artykule. Zobacz SDK projektów .NET .

Logika kompilacji zaimportowana przez standardowe pliki .csproj obsługuje o wiele więcej opcji i znacznie bardziej złożony proces kompilacji niż w tym przykładzie.

Aby uzyskać informacje na temat tworzenia pliku projektu dla projektu C++, zobacz MSBuild (C++).

W tym samouczku pokazano, jak przyrostowo utworzyć podstawowy plik projektu przy użyciu tylko edytora tekstów. Przewodnik przebiega zgodnie z następującymi krokami:

Rozszerz zmienną środowiskową PATH.
Utwórz minimalny plik źródłowy aplikacji.
Utwórz minimalny plik projektu MSBuild.
Skompiluj aplikację przy użyciu pliku projektu.
Dodaj właściwości, aby kontrolować kompilację.
Kontroluj kompilację, zmieniając wartości właściwości.
Dodaj elementy docelowe do kompilacji.
Kontroluj kompilację, określając cele.
Buduj przyrostowo.

W tym samouczku pokazano, jak skompilować projekt w wierszu polecenia i sprawdzić wyniki. Aby uzyskać więcej informacji o programie MSBuild i sposobie uruchamiania programu MSBuild w wierszu polecenia, zobacz Use MSBuild.

Aby ukończyć samouczek, musisz mieć zainstalowany program Visual Studio, ponieważ zawiera program MSBuild i kompilator języka C#, który jest wymagany do przewodnika.

Rozszerzanie ścieżki

Przed rozpoczęciem korzystania z programu MSBuild należy rozszerzyć zmienną środowiskową PATH, aby uwzględnić wszystkie wymagane narzędzia.

Jeśli korzystasz z systemu Windows, możesz użyć wiersza polecenia Developer dla programu Visual Studio. Wyszukaj je w polu wyszukiwania systemu Windows na pasku zadań systemu Windows. Aby skonfigurować środowisko w zwykłym wierszu polecenia lub w środowisku skryptowym, uruchom VSDevCmd.bat w podfolderze Common7/Tools instalacji programu Visual Studio.

Tworzenie minimalnej aplikacji

W tej sekcji pokazano, jak utworzyć minimalny plik źródłowy aplikacji języka C# przy użyciu edytora tekstów.

W wierszu polecenia przejdź do folderu, w którym chcesz utworzyć aplikację, na przykład \My Documents\ lub \Desktop\.
Utwórz podfolder o nazwie \HelloWorld\ i zmień katalog, aby przejść do niego.

W edytorze tekstów utwórz nowy plik HelloWorld.cs, a następnie skopiuj i wklej następujący kod:

using System;

class HelloWorld
{
    static void Main()
    {
#if DebugConfig
        Console.WriteLine("WE ARE IN THE DEBUG CONFIGURATION");
#endif

        Console.WriteLine("Hello, world!");
    }
}

Skompiluj aplikację, wpisując csc helloworld.cs w wierszu polecenia.
Przetestuj aplikację, wpisując helloworld w wierszu polecenia.

Witaj, świecie! powinien zostać wyświetlony komunikat.
Usuń plik wykonywalny.

Tworzenie minimalnego pliku projektu MSBuild

Teraz, gdy masz minimalny plik źródłowy aplikacji, możesz utworzyć minimalny plik projektu w celu skompilowania aplikacji. Ten plik projektu zawiera następujące elementy:

Wymagany węzeł Project root.
Węzeł ItemGroup do przechowywania elementów.
Element, który odwołuje się do pliku źródłowego aplikacji.
Węzeł Target zawierający zadania wymagane do skompilowania aplikacji.
Element Task umożliwiający uruchomienie kompilatora języka C# w celu skompilowania aplikacji.

Aby utworzyć minimalny plik projektu MSBuild

W edytorze tekstów utwórz nowy plik HelloWorld.fromscratchproj i wprowadź następujący kod:
```
<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
</Project>
```
Ten ItemGroup zawiera element Compile i określa jeden plik źródłowy jako element.
Dodaj węzeł Target jako element podrzędny węzła Project. Nadaj węzłowi nazwę Build.
```
<Target Name="Build">
</Target>
```
Wstaw ten element zadania jako element podrzędny węzła Target:
```
<Csc Sources="@(Compile)"/>
```
Zapisz ten plik projektu i nadaj mu nazwę Helloworld.fromscratchproj.

Minimalny plik projektu powinien przypominać następujący kod:

<Project>
  <ItemGroup>
    <Compile Include="helloworld.cs"/>
  </ItemGroup>
  <Target Name="Build">
    <Csc Sources="@(Compile)"/>
  </Target>
</Project>

Zadania w obiekcie docelowym kompilacji są wykonywane sekwencyjnie. W tym przypadku zadanie kompilatora języka C# Csc jest jedynym zadaniem. Oczekuje listy plików źródłowych do skompilowania, a jest to określone przez wartość elementu Compile. Element Compile odwołuje się tylko do jednego pliku źródłowego, Helloworld.cs.

Notatka

W elemencie elementu można użyć symbolu wieloznacznego gwiazdki (*), aby odwołać się do wszystkich plików, które mają rozszerzenie nazwy pliku .cs w następujący sposób:

<Compile Include="*.cs" />

Kompilowanie aplikacji

Teraz, aby skompilować aplikację, użyj właśnie utworzonego pliku projektu.

W wierszu polecenia wpisz msbuild helloworld.fromscratchproj -t:Build.

Spowoduje to uruchomienie builda pliku projektu Helloworld przez wywołanie kompilatora języka C# w celu utworzenia aplikacji Helloworld.
Przetestuj aplikację, wpisując helloworld.

Witaj, świecie! powinien zostać wyświetlony komunikat.

Notatka

Więcej szczegółów dotyczących kompilacji można wyświetlić, zwiększając poziom szczegółowości. Aby ustawić poziom szczegółowości na "szczegółowy", wprowadź następujące polecenie w wierszu polecenia:

msbuild helloworld.fromscratchproj -t:Build -verbosity:detailed

Dodawanie właściwości kompilacji

Możesz dodać właściwości kompilacji do pliku projektu, aby dokładniej kontrolować kompilację. Teraz dodaj następujące właściwości:

Właściwość AssemblyName określająca nazwę aplikacji.
Właściwość OutputPath określająca folder, który ma zawierać aplikację.

Aby dodać właściwości kompilacji

Usuń istniejący plik wykonywalny aplikacji (później dodasz obiekt docelowy Clean do obsługi usuwania starych plików wyjściowych).

W pliku projektu wstaw ten element PropertyGroup tuż po otwarciu elementu Project:

<PropertyGroup>
  <AssemblyName>MSBuildSample</AssemblyName>
  <OutputPath>Bin\</OutputPath>
</PropertyGroup>

Dodaj to zadanie do obiektu docelowego kompilacji tuż przed zadaniem Csc:
```
<MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
```
Zadanie MakeDir tworzy folder o nazwie ustalonej przez właściwość OutputPath, pod warunkiem że obecnie nie istnieje żaden folder o tej nazwie.
Dodaj ten atrybut OutputAssembly do zadania Csc:
```
<Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
```
Spowoduje to, że kompilator języka C# utworzy zestaw o nazwie wskazanej przez właściwość AssemblyName i umieści go w folderze o nazwie wskazanej przez właściwość OutputPath.
Zapisz zmiany.

Plik projektu powinien teraz wyglądać podobnie do następującego kodu:

<Project>
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
</Project>

Notatka

Zalecamy dodanie znaku ukośnika odwrotnego (\) na końcu nazwy folderu, gdy określasz go w elemencie OutputPath, zamiast dodawać go w atrybucie OutputAssembly zadania Csc. Więc

<OutputPath>Bin\</OutputPath>

OutputAssembly="$(OutputPath)$(AssemblyName).exe" />

jest lepszy niż

<OutputPath>Bin</OutputPath>

OutputAssembly="$(OutputPath)\$(AssemblyName).exe" />

Testowanie właściwości kompilacji

Teraz możesz skompilować aplikację przy użyciu pliku projektu, w którym użyto właściwości kompilacji do określenia folderu wyjściowego i nazwy aplikacji.

W wierszu polecenia wpisz msbuild helloworld.fromscratchproj -t:Build.

Spowoduje to utworzenie folderu \Bin\, a następnie wywoła kompilator języka C#, aby utworzyć aplikację MSBuildSample i umieścić ją w folderze \Bin\.
Aby sprawdzić, czy folder \Bin\ został utworzony i czy zawiera aplikację MSBuildSample, wpisz dir Bin.
Przetestuj aplikację, wpisując Bin\MSBuildSample, aby uruchomić plik wykonywalny.

Witaj, świecie! powinien zostać wyświetlony komunikat.

Dodawanie obiektów docelowych kompilacji

Następnie dodaj dwa kolejne elementy docelowe do pliku projektu w następujący sposób:

Czysty element docelowy, który usuwa stare pliki.
Cel ponownego kompilowania, który używa atrybutu DependsOnTargets, aby wymusić uruchomienie zadania Clean przed zadaniem kompilacji.

Teraz, gdy masz wiele celów, możesz ustawić cel kompilacji jako domyślny cel.

Aby dodać obiekty docelowe kompilacji

W pliku projektu dodaj te dwa obiekty docelowe tuż po obiekcie docelowym kompilacji:
```
<Target Name="Clean" >
  <Delete Files="$(OutputPath)$(AssemblyName).exe" />
</Target>
<Target Name="Rebuild" DependsOnTargets="Clean;Build" />
```
Obiekt docelowy Clean wywołuje zadanie Usuń, aby usunąć aplikację. Cel ponownej kompilacji nie jest uruchamiany, dopóki nie zostaną uruchomione zarówno cel Clean, jak i cel kompilacji. Mimo że cel Rebuild nie ma żadnych zadań, powoduje uruchomienie celu Clean przed celem Build.
Dodaj ten atrybut DefaultTargets do elementu otwierającego Project:
```
<Project DefaultTargets="Build">
```
Ustawia cel kompilacji jako domyślny.

Plik projektu powinien teraz wyglądać podobnie do następującego kodu:

<Project DefaultTargets="Build">
  <PropertyGroup>
    <AssemblyName>MSBuildSample</AssemblyName>
    <OutputPath>Bin\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Clean" >
    <Delete Files="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Rebuild" DependsOnTargets="Clean;Build" />
</Project>

Testowanie celów kompilacji

Można użyć nowych celów budowania, aby przetestować te funkcje pliku projektu.

Budowanie domyślnej kompilacji.
Ustawianie nazwy aplikacji w wierszu polecenia.
Usuwanie aplikacji przed skompilowaniem innej aplikacji.
Usuwanie aplikacji bez kompilowania innej aplikacji.

Aby przetestować cele kompilacji

W wierszu polecenia wpisz msbuild helloworld.fromscratchproj -p:AssemblyName=Greetings.

Ponieważ nie użyto przełącznika -t do jawnego ustawienia celu, MSBuild uruchamia domyślny cel kompilacji. Przełącznik -p zastępuje właściwość AssemblyName i nadaje jej nową wartość Greetings. Spowoduje to utworzenie nowej aplikacji Greetings.exew folderze \Bin\.
Aby sprawdzić, czy folder \Bin\ zawiera zarówno aplikację MSBuildSample, jak i nową aplikację Greetings, wpisz dir Bin.
Przetestuj aplikację Greetings (na przykład, wpisując Bin\Greetings w systemie Windows).

Witaj, świecie! powinien zostać wyświetlony komunikat.
Usuń aplikację MSBuildSample, wpisując msbuild helloworld.fromscratchproj -t:clean.

Spowoduje to uruchomienie zadania Clean w celu usunięcia aplikacji, która ma domyślną wartość właściwości AssemblyName, MSBuildSample.
Usuń aplikację Greetings, wpisując msbuild helloworld.fromscratchproj -t:clean -p:AssemblyName=Greetings.

Spowoduje to uruchomienie zadania Clean w celu usunięcia aplikacji, która ma podaną wartość właściwości AssemblyNameGreetings.
Aby sprawdzić, czy folder \Bin\ jest teraz pusty, wpisz dir Bin.
Wpisz msbuild.

Mimo że plik projektu nie jest określony, program MSBuild kompiluje plik helloworld.fromscratchproj, ponieważ w bieżącym folderze znajduje się tylko jeden plik projektu. Powoduje to utworzenie aplikacji MSBuildSample w folderze \Bin\.

Aby sprawdzić, czy folder \Bin\ zawiera aplikację MSBuildSample, wpisz dir Bin.

Budowanie przyrostowe

Program MSBuild może skompilować element docelowy tylko wtedy, gdy pliki źródłowe lub pliki docelowe, od których zależy element docelowy, uległy zmianie. Program MSBuild używa sygnatury czasowej pliku, aby określić, czy został zmieniony.

Aby budować przyrostowo

W pliku projektu dodaj następujące atrybuty do otwierającego elementu docelowego kompilacji:
```
Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe"
```
Określa to, że element docelowy kompilacji zależy od plików wejściowych określonych w grupie elementów Compile, a element docelowy danych wyjściowych jest plikiem aplikacji.

Wynikowy element docelowy kompilacji powinien przypominać następujący kod:
```
<Target Name="Build" Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe">
  <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
  <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
</Target>
```
Przetestuj cel kompilacji, wpisując msbuild -v:d w wierszu polecenia.

Pamiętaj, że helloworld.fromscratchproj jest domyślnym plikiem projektu, a Build jest domyślnym obiektem docelowym.

Przełącznik -v:d to skrót -verbosity:detailed, którego używałeś wcześniej.

Jeśli dane wyjściowe zostały już skompilowane, powinny zostać wyświetlone następujące wiersze:

pomijanie docelowego elementu "Kompilacja", ponieważ wszystkie pliki wyjściowe są up-to-date w odniesieniu do plików wejściowych.

Program MSBuild pomija element docelowy kompilacji, ponieważ żaden z plików źródłowych nie zmienił się od czasu ostatniej kompilacji aplikacji.

Przykład w języku C#

Poniższy przykład przedstawia plik projektu, który kompiluje aplikację języka C# i rejestruje komunikat zawierający nazwę pliku wyjściowego.

Kod

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldCS</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <CSFile Include = "*.cs"/>
    </ItemGroup>

    <Target Name="Compile">
        <!-- Run the C# compilation using input files of type CSFile -->
        <CSC
            Sources = "@(CSFile)"
            OutputAssembly = "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the CSC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </CSC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Przykład języka Visual Basic

Poniższy przykład przedstawia plik projektu, który kompiluje aplikację języka Visual Basic i rejestruje komunikat zawierający nazwę pliku wyjściowego.

Kod

<Project DefaultTargets = "Compile">

    <!-- Set the application name as a property -->
    <PropertyGroup>
        <appname>HelloWorldVB</appname>
    </PropertyGroup>

    <!-- Specify the inputs by type and file name -->
    <ItemGroup>
        <VBFile Include = "consolehwvb1.vb"/>
    </ItemGroup>

    <Target Name = "Compile">
        <!-- Run the Visual Basic compilation using input files of type VBFile -->
        <VBC
            Sources = "@(VBFile)"
            OutputAssembly= "$(appname).exe">
            <!-- Set the OutputAssembly attribute of the VBC task
            to the name of the executable file that is created -->
            <Output
                TaskParameter = "OutputAssembly"
                ItemName = "EXEFile" />
        </VBC>
        <!-- Log the file name of the output file -->
        <Message Text="The output file is @(EXEFile)"/>
    </Target>
</Project>

Co dalej?

Program Visual Studio może automatycznie wykonać większość pracy, która jest wyświetlana w tym przewodniku. Aby dowiedzieć się, jak używać programu Visual Studio do tworzenia, edytowania, kompilowania i testowania plików projektów MSBuild, zobacz Use MSBuild.

omówienie programu MSBuild
Dokumentacja programu MSBuild

Udostępnij za pośrednictwem

Tworzenie pliku projektu MSBuild od podstaw

Rozszerzanie ścieżki

Tworzenie minimalnej aplikacji

Tworzenie minimalnego pliku projektu MSBuild

Aby utworzyć minimalny plik projektu MSBuild

Kompilowanie aplikacji

Dodawanie właściwości kompilacji

Aby dodać właściwości kompilacji

Testowanie właściwości kompilacji

Dodawanie obiektów docelowych kompilacji

Aby dodać obiekty docelowe kompilacji

Testowanie celów kompilacji

Aby przetestować cele kompilacji

Budowanie przyrostowe

Aby budować przyrostowo

Przykład w języku C#

Kod

Przykład języka Visual Basic

Kod

Co dalej?

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Tworzenie pliku projektu MSBuild od podstaw

Rozszerzanie ścieżki

Tworzenie minimalnej aplikacji

Tworzenie minimalnego pliku projektu MSBuild

Aby utworzyć minimalny plik projektu MSBuild

Kompilowanie aplikacji

Dodawanie właściwości kompilacji

Aby dodać właściwości kompilacji

Testowanie właściwości kompilacji

Dodawanie obiektów docelowych kompilacji

Aby dodać obiekty docelowe kompilacji

Testowanie celów kompilacji

Aby przetestować cele kompilacji

Budowanie przyrostowe

Aby budować przyrostowo

Przykład w języku C#

Kod

Przykład języka Visual Basic

Kod

Co dalej?

Powiązana zawartość

Opinia

Dodatkowe zasoby