MSBuild プロパティMSBuild Properties

プロパティはビルドを設定するための名前と値のペアです。Properties are name-value pairs that can be used to configure builds. プロパティを使用することで、タスクに値を渡したり、条件を評価したりできるだけでなく、プロジェクト ファイルで参照する値を格納しておくこともできます。Properties are useful for passing values to tasks, evaluating conditions, and storing values that will be referenced throughout the project file.

プロジェクト ファイルでのプロパティの定義と参照Defining and Referencing Properties in a Project File

プロパティを宣言するには、そのプロパティの名前を持つ要素を PropertyGroup 要素の子として作成します。Properties are declared by creating an element that has the name of the property as a child of a PropertyGroup element. たとえば、次の XML では、BuildDir という名前のプロパティを作成し、Build を値として設定しています。For example, the following XML creates a property named BuildDir that has a value of Build.

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

プロジェクト ファイルでプロパティを参照するには、$(PropertyName) という構文を使用します。Throughout the project file, properties are referenced by using the syntax $(PropertyName). たとえば、前の例に示したプロパティを参照するには、$(BuildDir) と記述します。For example, the property in the previous example is referenced by using $(BuildDir).

プロパティ値を変更するには、プロパティを再定義します。Property values can be changed by redefining the property. BuildDir プロパティに新しい値を設定するには、次の XML を使用します。The BuildDir property can be given a new value by using this XML:

<PropertyGroup>  
    <BuildDir>Alternate</BuildDir>  
</PropertyGroup>  

プロパティは、プロジェクト ファイルに表示される順に評価されます。Properties are evaluated in the order in which they appear in the project file. BuildDir の新しい値は、古い値が割り当てられた後で宣言する必要があります。The new value for BuildDir must be declared after the old value is assigned.

予約済みのプロパティReserved Properties

MSBuild では、プロジェクト ファイルに関する情報や MSBuild のバイナリに関する情報を保持するために、いくつかのプロパティ名が予約されています。MSBuild reserves some property names to store information about the project file and the MSBuild binaries. これらのプロパティは、他のプロパティと同じように $ 表記を使用して参照できます。These properties are referenced by using the $ notation, just like any other property. たとえば、$(MSBuildProjectFile) は、ファイル名の拡張子を含むプロジェクト ファイルの完全なファイル名を返します。For example, $(MSBuildProjectFile) returns the complete file name of the project file, including the file name extension.

詳細については、「方法: プロジェクト ファイルの名前または場所を参照する」および「MSBuild の予約済みおよび既知のプロパティ」を参照してください。For more information, see How to: Reference the Name or Location of the Project File and MSBuild Reserved and Well-Known Properties.

環境プロパティEnvironment Properties

プロジェクト ファイルで環境変数を参照する場合も、予約済みのプロパティを参照するときと同じ方法を使用します。You can reference environment variables in project files just as you reference reserved properties. たとえば、プロジェクト ファイルで PATH 環境変数を使用するには、$(Path) と記述します。For example, to use the PATH environment variable in your project file, use $(Path). プロジェクト ファイルに、環境プロパティと同じ名前のプロパティが定義されている場合、環境変数の値はプロジェクト内のプロパティによってオーバーライドされます。If the project contains a property definition that has the same name as an environment property, the property in the project overrides the value of the environment variable.

各 MSBuild プロジェクトには、分離された環境ブロックがあります。各プロジェクトは独自のブロックに対する読み取りと書き込みのみを参照します。Each MSBuild project has an isolated environment block: it only sees reads and writes to its own block. プロジェクト ファイルの評価やビルドを行う前、MSBuild では、プロパティ コレクションが初期化されるときに環境変数のみを読み取ります。MSBuild only reads environment variables when it initializes the property collection, before the project file is evaluated or built. その後で、環境プロパティは静的なプロパティになります。つまり、起動されたツールは、同じ名前と値で実行が開始されます。After that, environment properties are static, that is, each spawned tool starts with the same names and values.

起動されたツール内から環境変数の現在の値を取得するには、プロパティ関数 System.Environment.GetEnvironmentVariable を使用します。To get the current value of environment variables from within a spawned tool, use the Property Functions System.Environment.GetEnvironmentVariable. ただし推奨される方法は、タスク パラメーター EnvironmentVariables を使用する方法です。The preferred method, however, is to use the task parameter EnvironmentVariables. この文字列配列に設定されている環境プロパティは、起動されたツールに渡すことができます。このとき、システム環境変数は影響を受けません。Environment properties set in this string array can be passed to the spawned tool without affecting the system environment variables.

ヒント

すべての環境変数が読み取られて、初期プロパティになるわけではありません。Not all environment variables are read in to become initial properties. 有効な MSBuild プロパティ名 ("386" など) を名前として持っていない環境変数は無視されます。Any environment variable whose name is not a valid MSBuild property names, such as "386", is ignored.

詳細については、「方法: ビルドで環境変数を使用する」を参照してください。For more information, see How to: Use Environment Variables in a Build.

レジストリのプロパティRegistry Properties

システム レジストリ値を読み取るには、次の構文を使用します。ここで、Hive はレジストリ ハイブ (たとえば、HKEY_LOCAL_MACHINE)、Key はキー名、SubKey はサブキー名、Value はサブキーの値をそれぞれ表します。You can read system registry values by using the following syntax, where Hive is the registry hive (for example, HKEY_LOCAL_MACHINE ), Key is the key name, SubKey is the subkey name, and Value is the value of the subkey.

$(registry:Hive\MyKey\MySubKey@Value)  

既定のサブキー値を取得するには、Value を省略します。To get the default subkey value, omit the Value.

$(registry:Hive\MyKey\MySubKey)  

このレジストリ値を使用して、ビルド プロパティを初期化できます。This registry value can be used to initialize a build property. たとえば、Visual Studio の Web ブラウザーのホーム ページを表すビルド プロパティを作成するには、次のコードを使用します。For example, to create a build property that represents the Visual Studio web browser home page, use this code:

<PropertyGroup>  
  <VisualStudioWebBrowserHomePage>  
    $(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\14.0\WebBrowser@HomePage)  
  </VisualStudioWebBrowserHomePage>  
<PropertyGroup>  

グローバル プロパティGlobal Properties

MSBuild では、/property (または /p) スイッチを使用してコマンド ラインからプロパティを設定できます。MSBuild lets you set properties on the command line by using the /property (or /p) switch. これらのグローバル プロパティ値は、プロジェクト ファイルで設定されたプロパティ値をオーバーライドします。These global property values override property values that are set in the project file. これには環境プロパティは含まれますが、予約済みのプロパティは含まれません。予約済みのプロパティは変更できません。This includes environment properties, but does not include reserved properties, which cannot be changed.

グローバルな Configuration プロパティを DEBUG に設定する例を次に示します。The following example sets the global Configuration property to DEBUG.

msbuild.exe MyProj.proj /p:Configuration=DEBUG  

グローバル プロパティは、MSBuild タスクの Properties 属性を使用することで、複数プロジェクトのビルドに含まれる子プロジェクトに対して設定または変更することもできます。Global properties can also be set or modified for child projects in a multi-project build by using the Properties attribute of the MSBuild task. グローバル プロパティは、MSBuild タスクの RemoveProperties 属性が転送しないプロパティの一覧を指定するために使用されていなければ、子プロジェクトにも転送されます。Global properties are also forwarded to child projects unless the RemoveProperties attribute of the MSBuild task is used to specify the list of proerties not to forward. 詳細については、「MSBuild タスク」を参照してください。For more information, see MSBuild Task.

プロジェクト タグで TreatAsLocalProperty 属性を使用してプロパティを指定する場合、そのグローバル プロパティ値は、プロジェクト ファイルで設定されているプロパティ値をオーバーライドしません。If you specify a property by using the TreatAsLocalProperty attribute in a project tag, that global property value doesn't override the property value that's set in the project file. 詳細については、「Project 要素 (MSBuild)」「How to: Build the Same Source Files with Different Options (方法: 同じソース ファイルを異なるオプションでビルドする)」を参照してください。For more information, see Project Element (MSBuild) and How to: Build the Same Source Files with Different Options.

プロパティ関数Property Functions

.NET Framework Version 4 以降では、プロパティ関数を使用して MSBuild スクリプトを評価できるようになりました。Starting in .NET Framework version 4, you can use property functions to evaluate your MSBuild scripts. MSBuild タスクを使用しなくても、システム時刻の読み取り、文字列の比較、正規表現の照合、その他のさまざまな処理をビルド スクリプト内で実行できます。You can read the system time, compare strings, match regular expressions, and perform many other actions within your build script without using MSBuild tasks.

文字列 (インスタンス) メソッドを使用してプロパティ値を操作したり、各種システム クラスの静的メソッドを呼び出したりできます。You can use string (instance) methods to operate on any property value, and you can call the static methods of many system classes. たとえば、ビルド プロパティを今日の日付に設定するには、次のようにします。For example, you can set a build property to today's date as follows.

<Today>$([System.DateTime]::Now.ToString("yyyy.MM.dd"))</Today>  

プロパティ関数の詳細と、プロパティ関数の一覧については、「プロパティ関数」を参照してください。For more information, and a list of property functions, see Property Functions.

実行時のプロパティの作成Creating Properties During Execution

Target 要素の外側にあるプロパティには、ビルドの評価フェーズで値が割り当てられます。Properties positioned outside Target elements are assigned values during the evaluation phase of a build. その後の実行フェーズでプロパティを作成または変更するには、次のようにします。During the subsequent execution phase, properties can be created or modified as follows:

  • プロパティはどのタスクでも生成できます。A property can be emitted by any task. プロパティを生成するには、Task 要素の子要素として、PropertyName 属性を持つ Output 要素を持つ必要があります。To emit a property, the Task element must have a child Output element that has a PropertyName attribute.

  • プロパティは CreateProperty タスクによって生成できます。A property can be emitted by the CreateProperty task. この使用法は推奨されていません。This usage is deprecated.

  • .NET Framework 3.5 以降では、プロパティ宣言を格納できる Target 要素を PropertyGroup 要素に含めることができます。Starting in the .NET Framework 3.5, Target elements may contain PropertyGroup elements that may contain property declarations.

プロパティに XML を格納するStoring XML in Properties

プロパティには、タスクに値を渡したり、ログ情報を表示したりするための任意の XML を格納できます。Properties can contain arbitrary XML, which can help in passing values to tasks or displaying logging information. 次の例では、ConfigTemplate プロパティの値に、XML や他のプロパティ参照が使用されています。The following example shows the ConfigTemplate property, which has a value that contains XML and other property references. このプロパティ参照は、MSBuildMSBuild により、対応するプロパティ値を使用して置き換えられます。MSBuildMSBuild replaces the property references by using their respective property values. プロパティ値は表示される順に割り当てられます。Property values are assigned in the order in which they appear. したがって、この例では、$(MySupportedVersion)$(MyRequiredVersion)、および $(MySafeMode) は既に定義されています。Therefore, in this example, $(MySupportedVersion), $(MyRequiredVersion), and $(MySafeMode) should have already been defined.


<PropertyGroup>  
    <ConfigTemplate>  
        <Configuration>  
            <Startup>  
                <SupportedRuntime  
                    ImageVersion="$(MySupportedVersion)"  
                    Version="$(MySupportedVersion)"/>  
                <RequiredRuntime  
                    ImageVersion="$(MyRequiredVersion)"  
                    Version="$(MyRequiredVersion)"  
                    SafeMode="$(MySafeMode)"/>  
            </Startup>  
        </Configuration>  
    </ConfigTemplate>  
</PropertyGroup>  

関連項目See Also

MSBuild の概念MSBuild Concepts
MSBuildMSBuild
方法: ビルドで環境変数を使用する How to: Use Environment Variables in a Build
方法: プロジェクト ファイルの名前または場所を参照する How to: Reference the Name or Location of the Project File
方法: 同じソース ファイルを異なるオプションでビルドする How to: Build the Same Source Files with Different Options
MSBuild の予約済みおよび既知のプロパティ MSBuild Reserved and Well-Known Properties
Property 要素 (MSBuild)Property Element (MSBuild)