共用方式為

逐步解說：從頭開始建立 MSBuild 專案檔案

  • 發行項

以 .NET Framework 為目標的程式語言 (如 Visual C# 和 Visual Basic) 會使用 MSBuild 專案檔來描述及控制應用程式建置流程。當您使用 Visual Studio 建立 MSBuild 專案檔時，檔案中會自動加入適當的 XML。然而，您可能會發現了解 XML 的組織方式以及要如何變更 XML 來控制建置，對您很有幫助。此逐步解說顯示如何僅使用文字編輯器來累加建立基本專案檔。這個逐步解說依照下列步驟進行：

  • 建立最小的應用程式原始程式檔。

  • 建立最小的 MSBuild 專案檔。

  • 擴充 PATH 環境變數以包含 MSBuild。

  • 使用專案檔建置應用程式。

  • 加入屬性以控制建置。

  • 藉由變更屬性值來控制建置。

  • 將目標加入到建置。

  • 藉由指定目標來控制建置。

  • 累加建置。

此逐步解說顯示如何在命令提示字元建立專案及檢查結果。如需 MSBuild 以及如何在命令提示字元執行 MSBuild 的詳細資訊，請參閱 逐步解說：使用 MSBuild。

若要完成此逐步解說，您必須已安裝 .NET Framework (2.0、3.5 或 4 版)，因為它包含此逐步解說所需的 MSBuild 和 Visual C# 編譯器。

建立最小的應用程式

本節顯示如何使用文字編輯器建立最小的 Visual C# 應用程式原始程式檔。

若要建立最小的應用程式

  1. 在命令提示字元中，瀏覽至您要建立應用程式的資料夾，如 \My Documents\ 或 \Desktop\。

  2. 輸入 md HelloWorld 以建立名為 \HelloWorld\ 的子資料夾。

  3. 輸入 cd HelloWorld 以變更至新資料夾。

  4. 啟動記事本或其他文字編輯器，然後輸入下列程式碼。

    using System;

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

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

  5. 儲存此原始程式碼檔並命名為 Helloworld.cs。

  6. 在命令提示字元上輸入 csc helloworld.cs，以建置應用程式。

  7. 在命令提示字元上輸入 helloworld，以測試應用程式。

    Hello, world! 訊息應該會顯示。

  8. 在命令提示字元上輸入 del helloworld.exe，以刪除應用程式。

建立最小的 MSBuild 專案檔

現在您已擁有最小的應用程式原始程式檔，可以建立最小的專案檔，進而建置應用程式。這個專案檔包含下列項目：

  • 必要的 Project 根節點。

  • 要包含項目的項目 (Item Element) 的 ItemGroup 節點。

  • 表示應用程式原始程式檔之項目的項目 (Item Element)。

  • 要包含建置應用程式所需之工作的 Target 節點。

  • 用於啟動 Visual C# 編譯器來建置應用程式的 Task 項目 (Element)。

若要建立最小的 MSBuild 專案檔

  1. 在文字編輯器中，使用下列兩行來取代現有的文字：

    <Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
</Project>

  2. 插入此 ItemGroup 節點，做為 Project 節點的子項目：

      <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>

    請注意，此 ItemGroup 已經包含一個項目的項目 (Item Element)。

  3. 加入 Target 節點，做為 Project 節點的子項目。將此節點命名為 Build。

      <Target Name="Build">
  </Target>

  4. 插入此工作項目，做為 Target 節點的子項目：

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

  5. 儲存此專案檔並命名為 Helloworld.csproj。

您的最小專案檔應類似下列程式碼：

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <Compile Include="helloworld.cs" />
  </ItemGroup>
  <Target Name="Build">
    <Csc Sources="@(Compile)"/>  
  </Target>
</Project>

Build 目標中的工作會依序執行。在此案例中，Visual C# 編譯器 Csc 工作是唯一的工作。它需有要編譯的原始程式檔清單，而 Compile 項目的值會提供此清單。Compile 項目只會參考一個原始程式檔 Helloworld.cs。

注意事項注意事項

在項目的項目 (Item Element) 中，您可以使用星號萬用字元 (*) 來參考副檔名為 .cs 的所有檔案，如下所示：

<Compile Include="*.cs" />

但是，我們不建議使用萬用字元，因為如果加入或刪除了原始程式檔，它會使偵錯和標靶作業變得更加困難。

擴充 Path 以包含 MSBuild

您必須先擴充 PATH 環境變數以包含 .NET Framework 資料夾，才能存取 MSBuild。

若要擴充 Path 以包含 MSBuild

  • 在命令提示字元中輸入 set PATH=%PATH%;%WINDIR%\Microsoft.Net\Framework\v4.0。如果您安裝了其他版本的 .NET Framework，請據以變更版本號碼。

    注意事項注意事項

    電腦上的 MSBuild 資料夾名稱可能包含 v2.0.50727 之類的組建編號。若是如此，請在命令列上包含組建編號，例如 set PATH=%PATH%;%WINDIR%\Microsoft.Net\Framework\v2.0.50727。

    或者，如果您已安裝 Visual Studio，即可使用 [Visual Studio 命令提示字元]，它有一個內含 MSBuild 資料夾的路徑。

使用專案檔建置應用程式

現在若要建置應用程式，請使用您剛才建立的專案檔。

若要建置應用程式

  1. 在命令提示字元中輸入 msbuild helloworld.csproj /t:Build。

    這會叫用 Visual C# 編譯器來建立 Helloworld 應用程式，進而建置 Helloworld 專案檔的 Build 目標。

  2. 輸入 helloworld 以測試應用程式。

    Hello, world! 訊息應該會顯示。

注意事項注意事項

您可以提高詳細等級，以查看更多有關組建的詳細資料。若要將詳細等級設為「詳細」，請在命令提示字元輸入下列任一個命令：

msbuild helloworld.csproj /t:Build /verbosity:detailed

加入建置屬性

您可以將建置屬性加入至專案檔，進一步控制建置。請立即加入下列屬性：

  • AssemblyName 屬性，用於指定應用程式的名稱。

  • OutputPath 屬性，用於指定要包含應用程式的資料夾。

若要加入建置屬性

  1. 在命令提示字元上輸入 del helloworld.exe，以刪除現有的應用程式。

  2. 在專案檔中，將此 PropertyGroup 項目插入於開頭 Project 項目之後：

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

  3. 將此工作加入至 Build 目標中的 Csc 工作之前：

        <MakeDir Directories="$(OutputPath)"      Condition="!Exists('$(OutputPath)')" />

    MakeDir 工作會建立一個以 OutputPath 屬性 (Property) 命名的資料夾，但前提是目前不存在該名稱的資料夾。

  4. 將此 OutputAssembly 屬性 (Attribute) 加入至 Csc 工作：

    <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />

    這會指示 Visual C# 編譯器產生一個以 AssemblyName 屬性 (Property) 命名的組件，並將該組件放入以 OutputPath 屬性命名的資料夾中。

  5. 儲存您所作的變更。

您的專案檔現在應類似下列程式碼：

<Project xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <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>
注意事項注意事項

建議您在 OutputPath 項目中指定資料夾時，於資料夾名稱的結尾處加入反斜線 (\) 路徑分隔符號，而非在 Csc 工作的 OutputAssembly 屬性中加入此資料夾。因此，

<OutputPath>Bin\</OutputPath>

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

優於

<OutputPath>Bin</OutputPath>

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

測試建置屬性

您現在可以使用專案檔來建置應用程式，在此專案檔中您會使用建置屬性來指定輸出資料夾和應用程式名稱。

若要測試建置屬性

  1. 在命令提示字元中輸入 msbuild helloworld.csproj /t:Build。

    這會建置 \Bin\ 資料夾，然後叫用 Visual C# 編譯器，以建立 MSBuildSample 應用程式並將它放在 \Bin\ 資料夾中。

  2. 若要驗證 \Bin\ 資料夾是否已建立，以及該資料夾是否包含 MSBuildSample 應用程式，請輸入 dir Bin。

  3. 輸入 Bin\MSBuildSample 以測試應用程式。

    Hello, world! 訊息應該會顯示。

加入建置目標

接著，多加兩個目標至專案檔，如下所示：

  • Clean 目標，可刪除舊檔案。

  • Rebuild 目標，可使用 DependsOnTargets 屬性強制 Clean 工作於 Build 工作之前執行。

您現在擁有多個目標，可以將 Build 目標設為預設目標。

若要加入建置目標

  1. 在專案檔中，將下列兩個目標加入於 Build 目標之後：

      <Target Name="Clean" >
    <Delete Files="$(OutputPath)$(AssemblyName).exe" />
  </Target>
  <Target Name="Rebuild" DependsOnTargets="Clean;Build" />

    Clean 目標會叫用 Delete 工作以刪除應用程式。Clean 目標和 Build 目標都已執行之後，Rebuild 目標才會執行。雖然 Rebuild 目標沒有任何工作，但是它會導致 Clean 目標於 Build 目標之前執行。

  2. 將此 DefaultTargets 屬性加入至開頭的 Project 項目：

    <Project DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">

    這會將 Build 目標設為預設目標。

您的專案檔現在應類似下列程式碼：

<Project DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <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>

測試建置目標

您可以運用新的建置目標來測試專案檔的下列功能：

  • 建置預設組建。

  • 在命令提示字元上設定應用程式名稱。

  • 在建置其他應用程式之前，先刪除應用程式。

  • 刪除應用程式，但不建置其他應用程式。

若要測試建置目標

  1. 在命令提示字元中輸入 msbuild helloworld.csproj /p:AssemblyName=Greetings。

    因為您未使用 /t 參數明確設定目標，所以 MSBuild 會執行預設 Build 目標。/p 參數會覆寫 AssemblyName 屬性並提供新值 Greetings。這會在 \Bin\ 資料夾中建立新應用程式 Greetings.exe。

  2. 若要驗證 \Bin\ 資料夾是否同時包含 MSBuildSample 應用程式和新的 Greetings 應用程式，請輸入 dir Bin。

  3. 輸入 Bin\Greetings 以測試 Greetings 應用程式。

    Hello, world! 訊息應該會顯示。

  4. 輸入 msbuild helloworld.csproj /t:clean 以刪除 MSBuildSample 應用程式。

    這會執行 Clean 工作，以移除具有預設 AssemblyName 屬性值 MSBuildSample 的應用程式。

  5. 輸入 msbuild helloworld.csproj /t:clean /p:AssemblyName=Greetings 以刪除 Greetings 應用程式。

    這會執行 Clean 工作，以移除具有指定的 AssemblyName 屬性值 Greetings 的應用程式。

  6. 若要驗證 \Bin\ 資料夾目前是否為空的，請輸入 dir Bin。

  7. 輸入 msbuild。

    雖然未指定專案檔，但是 MSBuild 會建置 helloworld.csproj 檔，因為目前資料夾中只有一個專案檔。這會在 \Bin\ 資料夾中建立 MSBuildSample 應用程式。

    若要驗證 \Bin\ 資料夾是否包含 MSBuildSample 應用程式，請輸入 dir Bin。

累加建置

只有在目標相依的原始程式檔或目標檔案已變更時，您才可以告知 MSBuild 建置目標。MSBuild 會使用檔案的時間戳記來判斷檔案是否已變更。

若要累加建置

  1. 在專案檔中，將下列屬性加入於開頭的 Build 目標之後：

    Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe"

    這會指定 Build 目標相依於在 Compile 項目群組中指定的輸入檔，而輸出目標為應用程式檔案。

    結果產生的 Build 目標應類似下列程式碼：

    <Target Name="Build" Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe">
  <MakeDir Directories="$(OutputPath)" Condition="!Exists('$(OutputPath)')" />
  <Csc Sources="@(Compile)" OutputAssembly="$(OutputPath)$(AssemblyName).exe" />
</Target>

  2. 在命令提示字元上輸入 msbuild /v:d 以測試 Build 目標。

    請記住，helloworld.csproj 是預設專案檔，而 Build 是預設目標。

    /v:d 參數可指定建置流程的詳細資訊描述。

    應會顯示下列各行：

    Skipping target "Build" because all output files are up-to-date with respect to the input files.

    Input files: HelloWorld.cs

    Output files: Bin\MSBuildSample.exe

    MSBuild 會略過 Build 目標，因為自從上次建置應用程式之後，就沒有任何原始程式檔有所變更。

範例

Dd576348.collapse_all(zh-tw,VS.110).gif描述

下列範例說明編譯 Visual C# 應用程式的專案檔，其中記錄含有輸出檔名的訊息。

Dd576348.collapse_all(zh-tw,VS.110).gif程式碼

<Project DefaultTargets = "Compile"
    xmlns="https://schemas.microsoft.com/developer/msbuild/2003" >

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

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

    <Target Name = "Compile">
        <!-- Run the Visual 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>

範例

Dd576348.collapse_all(zh-tw,VS.110).gif描述

下列範例說明編譯 Visual Basic 應用程式的專案檔，其中記錄含有輸出檔名的訊息。

Dd576348.collapse_all(zh-tw,VS.110).gif程式碼

<Project DefaultTargets = "Compile"
    xmlns="https://schemas.microsoft.com/developer/msbuild/2003" >

    <!-- 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>

下一步

Visual Studio 可以自動進行此逐步解說中所述的大部分工作。若要了解如何使用 Visual Studio 來建立、編輯、建置和測試 MSBuild 專案檔，請參閱逐步解說：使用 MSBuild。

請參閱

其他資源

MSBuild

MSBuild 參考