MSBuild – úlohaMSBuild task

Vytvoří projekty MSBuild z jiného projektu MSBuild.Builds MSBuild projects from another MSBuild project.

ParametryParameters

Následující tabulka popisuje parametry MSBuild úkolu.The following table describes the parameters of the MSBuild task.

ParametrParameter PopisDescription
BuildInParallel Volitelný Boolean parametr.Optional Boolean parameter.

Pokud true je to možné, projekty zadané v Projects parametru jsou sestaveny paralelně.If true, the projects specified in the Projects parameter are built in parallel if it is possible. Výchozí je false.Default is false.
Projects Požadovaný parametr ITaskItem[].Required ITaskItem[] parameter.

Určuje soubory projektu, které se mají sestavit.Specifies the project files to build.
Properties Volitelný String parametr.Optional String parameter.

Čárkami oddělený seznam párů název/hodnota vlastnosti, které se použijí jako globální vlastnosti podřízeného projektu.A semicolon-delimited list of property name/value pairs to apply as global properties to the child project. Pokud zadáte tento parametr, je funkčně ekvivalentní nastavení vlastností, které mají přepínač -Property při sestavování pomocí MSBuild.exe.When you specify this parameter, it is functionally equivalent to setting properties that have the -property switch when you build with MSBuild.exe. Příklad:For example:

Properties="Configuration=Debug;Optimize=$(Optimize)"

Když předáte vlastnosti projektu prostřednictvím Properties parametru, MSBuild může vytvořit novou instanci projektu i v případě, že soubor projektu již byl načten.When you pass properties to the project through the Properties parameter, MSBuild might create a new instance of the project even if the project file has already been loaded. Nástroj MSBuild vytvoří jednu instanci projektu pro danou cestu projektu a jedinečnou sadu globálních vlastností.MSBuild creates a single project instance for a given project path and a unique set of global properties. Například toto chování umožňuje vytvořit více úloh nástroje MSBuild, které volají MyProject. proj s konfigurací = Release, a získáte jednu instanci MyProject. proj (Pokud v úloze nejsou zadány žádné jedinečné vlastnosti).For example, this behavior allows you to create multiple MSBuild tasks that call myproject.proj, with Configuration=Release and you get a single instance of myproject.proj (if no unique properties are specified in the task). Pokud zadáte vlastnost, která ještě nebyla v nástroji MSBuild zjištěna, nástroj MSBuild vytvoří novou instanci projektu, která může být sestavena paralelně s jinými instancemi projektu.If you specify a property that has not yet been seen by MSBuild, MSBuild creates a new instance of the project, which can be built in parallel to other instances of the project. Například konfigurace vydané verze může sestavovat ve stejnou dobu jako konfigurace ladění.For example, a Release configuration can build at the same time as a Debug configuration.
RebaseOutputs Volitelný Boolean parametr.Optional Boolean parameter.

Pokud jsou true relativní cesty cílových výstupních položek z sestavených projektů upraveny tak, aby byly relativní vzhledem k volajícímu projektu.If true, the relative paths of target output items from the built projects have their paths adjusted to be relative to the calling project. Výchozí je false.Default is false.
RemoveProperties Volitelný String parametr.Optional String parameter.

Určuje sadu globálních vlastností, které mají být odebrány.Specifies the set of global properties to remove.
RunEachTargetSeparately Volitelný Boolean parametr.Optional Boolean parameter.

V případě true , úloha MSBuild vyvolá každý cíl v seznamu předaného do nástroje MSBuild v jednom okamžiku, nikoli ve stejnou dobu.If true, the MSBuild task invokes each target in the list passed to MSBuild one at a time, instead of at the same time. Nastavením tohoto parametru true zajistíte, aby se vyvolaly další cíle i v případě, že se dřív vyvolaný cíl nezdařilSetting this parameter to true guarantees that subsequent targets are invoked even if previously invoked targets failed. V opačném případě chyba sestavení by zastavila vyvolání všech dalších cílů.Otherwise, a build error would stop invocation of all subsequent targets. Výchozí je false.Default is false.
SkipNonexistentProjects Volitelný Boolean parametr.Optional Boolean parameter.

Pokud se true soubory projektu, které na disku neexistují, přeskočí.If true, project files that do not exist on the disk will be skipped. Jinak takové projekty způsobí chybu.Otherwise, such projects will cause an error.
SkipNonexistentTargets Volitelný Boolean parametr.Optional Boolean parameter.

trueV případě, že soubory projektu, které existují, ale neobsahují název, se Targets přeskočí.If true, project files that exist but do not contain the named Targets will be skipped. Jinak takové projekty způsobí chybu.Otherwise, such projects will cause an error. Představeno v MSBuild 15,5.Introduced in MSBuild 15.5.
StopOnFirstFailure Volitelný Boolean parametr.Optional Boolean parameter.

Pokud true je v případě, že se jeden z projektů nepovede sestavit, nebudou sestaveny žádné další projekty.If true, when one of the projects fails to build, no more projects will be built. V současné době není tato podpora podporována při paralelním sestavování (s více procesory).Currently this is not supported when building in parallel (with multiple processors).
TargetAndPropertyListSeparators Volitelný String[] parametr.Optional String[] parameter.

Určuje seznam cílů a vlastností jako Project metadata položky.Specifies a list of targets and properties as Project item metadata). Oddělovače budou před zpracováním uvozeny řídicími znaky.Separators will be un-escaped before processing. například% 3B (řídicí znak '; ') bude považován za, jako by šlo o neřídicí znak '; '.e.g. %3B (an escaped ';') will be treated as if it were an un-escaped ';'.
TargetOutputs Volitelný ITaskItem [] výstupní parametr jen pro čtení.Optional ITaskItem[] read-only output parameter.

Vrátí výstupy sestavených cílů ze všech souborů projektu.Returns the outputs of the built targets from all the project files. Vrátí se jenom výstupy z určených cílů, ne všechny výstupy, které můžou existovat na cílících, na kterých jsou tyto cíle závislé.Only the outputs from the targets that were specified are returned, not any outputs that may exist on targets that those targets depend on.

TargetOutputsParametr obsahuje také následující metadata:The TargetOutputs parameter also contains the following metadata:

- MSBuildSourceProjectFile: Soubor projektu MSBuild obsahující cíl, který nastaví výstupy.- MSBuildSourceProjectFile: The MSBuild project file that contains the target that set the outputs.
- MSBuildSourceTargetName: Cíl, který nastavuje výstupy.- MSBuildSourceTargetName: The target that set the outputs. Poznámka: Chcete-li identifikovat výstupy z každého souboru projektu nebo cíle samostatně, spusťte MSBuild úlohu samostatně pro každý soubor projektu nebo cíl.Note: If you want to identify the outputs from each project file or target separately, run the MSBuild task separately for each project file or target. Pokud úlohu spouštíte MSBuild pouze jednou pro sestavení všech souborů projektu, výstupy všech cílů jsou shromažďovány do jednoho pole.If you run the MSBuild task only once to build all the project files, the outputs of all the targets are collected into one array.
Targets Volitelný String parametr.Optional String parameter.

Určuje cíl nebo cíle, které se mají sestavit v souborech projektu.Specifies the target or targets to build in the project files. K oddělení seznamu cílových názvů použijte středník.Use a semicolon to separate a list of target names. Nejsou-li v úloze zadány žádné cíle MSBuild , jsou vytvořeny výchozí cíle zadané v souborech projektu.If no targets are specified in the MSBuild task, the default targets specified in the project files are built. Poznámka: Cíle musí být provedeny ve všech souborech projektu.Note: The targets must occur in all the project files. Pokud ne, dojde k chybě sestavení.If they do not, a build error occurs.
ToolsVersion Volitelný String parametr.Optional String parameter.

Určuje, ToolsVersion který má být použit při sestavování projektů předaných této úloze.Specifies the ToolsVersion to use when building projects passed to this task.

Umožňuje úloze MSBuild sestavit projekt, který cílí na jinou verzi .NET Framework než v projektu, který je zadaný v projektu.Enables an MSBuild task to build a project that targets a different version of the .NET Framework than the one specified in the project. Platné hodnoty jsou 2.0 3.0 a 3.5 .Valid values are 2.0, 3.0 and 3.5. Výchozí hodnota je 3.5.Default value is 3.5.

PoznámkyRemarks

Kromě výše uvedených parametrů Tato úloha dědí parametry z TaskExtension třídy, která sama dědí z Task třídy.In addition to the parameters listed above, this task inherits parameters from the TaskExtension class, which itself inherits from the Task class. Seznam těchto dalších parametrů a jejich popis naleznete v tématu TaskExtension – Base Class.For a list of these additional parameters and their descriptions, see TaskExtension base class.

Na rozdíl od použití úlohy exec ke spuštění MSBuild.exe používá tato úloha stejný proces MSBuild pro sestavení podřízených projektů.Unlike using the Exec task to start MSBuild.exe, this task uses the same MSBuild process to build the child projects. Seznam již sestavených cílů, které lze přeskočit, je sdílen mezi nadřazeným a podřízeným sestavením.The list of already-built targets that can be skipped is shared between the parent and child builds. Tato úloha je taky rychlejší, protože se nevytvoří žádný nový proces MSBuild.This task is also faster because no new MSBuild process is created.

Tato úloha může zpracovat nejen soubory projektu, ale také soubory řešení.This task can process not only project files but also solution files.

Jakákoli konfigurace, kterou nástroj MSBuild vyžaduje k tomu, aby bylo možné projekty současně sestavit, i když konfigurace zahrnuje vzdálenou infrastrukturu (například porty, protokoly, vypršení časového limitu, opakování a tak dále), je nutné provést konfiguraci pomocí konfiguračního souboru.Any configuration that is required by MSBuild to enable projects to build at the same time, even if the configuration involves remote infrastructure (for example, ports, protocols, timeouts, retries, and so forth), must be made configurable by using a configuration file. Pokud je to možné, měly by být položky konfigurace možné zadat jako parametry úkolu v MSBuild úloze.When possible, configuration items should be able to be specified as task parameters on the MSBuild task.

Počínaje nástrojem MSBuild 3,5 projekty řešení nyní surfují TargetOutputs ze všech dílčích projektů, které sestavení vytvoří.Beginning in MSBuild 3.5, Solution projects now surface TargetOutputs from all of the sub-projects it builds.

Předat vlastnosti projektůmPass properties to projects

Ve verzích MSBuild před nástrojem MSBuild 3,5 předávání různých sad vlastností různým projektům uvedeným v položce MSBuild bylo náročné.In versions of MSBuild prior to MSBuild 3.5, passing different sets of properties to different projects listed in the MSBuild item was challenging. Pokud jste použili atribut Properties (vlastnosti) úlohy MSBuild, pak se jeho nastavení použilo pro všechny projekty, které jsou sestaveny, pokud jste nedávkují úlohu MSBuild a podmíněně neposkytly různé vlastnosti pro každý projekt v seznamu položek.If you used the Properties attribute of the MSBuild task, then its setting was applied to all of the projects being built unless you batched the MSBuild task and conditionally provided different properties for each project in the item list.

Nástroj MSBuild 3,5 však poskytuje dvě nové rezervované položky metadat, vlastnosti a AdditionalProperties, které poskytují flexibilní způsob, jak předat různé vlastnosti pro různé projekty sestavené pomocí úlohy MSBuild.MSBuild 3.5, however, provides two new reserved metadata items, Properties and AdditionalProperties, that provide you a flexible way to pass different properties for different projects being built using the MSBuild task.

Poznámka

Tyto nové položky metadat platí pouze pro položky předané v atributu Projects úlohy MSBuild.These new metadata items are applicable only to items passed in the Projects attribute of the MSBuild task.

Výhody sestavení s více procesoryMulti-processor build benefits

Jednou z hlavních výhod používání těchto nových metadat nastane při sestavování projektů paralelně v systému s více procesory.One of the major benefits of using this new metadata occurs when you build your projects in parallel on a multi-processor system. Metadata umožňují konsolidovat všechny projekty do jednoho volání úlohy MSBuild bez nutnosti provádět žádné dávkové nebo podmíněné úlohy MSBuild.The metadata allows you to consolidate all projects into a single MSBuild task call without having to perform any batching or conditional MSBuild tasks. A při volání pouze jedné úlohy MSBuildbudou všechny projekty, které jsou uvedeny v atributu Projects, sestaveny paralelně.And when you call only a single MSBuild task, all of the projects listed in the Projects attribute will be built in parallel. (Nicméně pokud BuildInParallel=true je atribut přítomen v úloze MSBuild.) Další informace najdete v tématu sestavení více projektů paralelně.(Only, however, if the BuildInParallel=true attribute is present in the MSBuild task.) For more information, see Build multiple projects in parallel.

Metadata vlastnostíProperties metadata

Po zadání vlastnosti metadata Přepisuje parametr vlastností úlohy, zatímco metadata AdditionalProperties jsou připojena k definicím parametru.When specified, Properties metadata overrides the task's Properties parameter, while AdditionalProperties metadata gets appended to the parameter's definitions.

Běžným scénářem je, když vytváříte více souborů řešení pomocí úlohy MSBuild, a to pouze pomocí různých konfigurací sestavení.A common scenario is when you are building multiple solution files using the MSBuild task, only using different build configurations. Můžete chtít sestavit řešení a1 pomocí konfigurace ladění a řešení a2 pomocí konfigurace vydané verze.You may want to build solution a1 using the Debug configuration and solution a2 using the Release configuration. V MSBuild 2,0 by tento soubor projektu vypadal jako následující:In MSBuild 2.0, this project file would look like the following:

Poznámka

V následujícím příkladu "..." představuje další soubory řešení.In the following example, "..." represents additional solution files.

a.proja.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Debug"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release"/>
    </Target>
</Project>

Pomocí vlastností metadat však můžete zjednodušit použití jedné úlohy MSBuild, jak je znázorněno v následujícím příkladu:By using the Properties metadata, however, you can simplify this to use a single MSBuild task, as shown by the following:

a.proja.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <Properties>Configuration=Debug</Properties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"/>
    </Target>
</Project>

- ani- or -

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln..."/>
        <ProjectToBuild Include="a2.sln">
            <Properties>Configuration=Release</Properties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Debug"/>
    </Target>
</Project>

Metadata AdditionalPropertiesAdditionalProperties metadata

Vezměte v úvahu následující scénář, kde vytváříte dva soubory řešení pomocí úlohy MSBuild, a to pomocí konfigurace vydané verze, ale jednoho pomocí architektury x86 a druhé pomocí architektury IA64.Consider the following scenario where you are building two solution files using the MSBuild task, both using the Release configuration, but one using the x86 architecture and the other using the ia64 architecture. V MSBuild 2,0 byste museli vytvořit více instancí úlohy MSBuild: jeden pro sestavení projektu pomocí konfigurace vydané verze s architekturou x86, druhá pomocí konfigurace vydané verze s architekturou ia64.In MSBuild 2.0, you would need to create multiple instances of the MSBuild task: one to build the project using the Release configuration with the x86 Architecture, the other using the Release configuration with the ia64 architecture. Váš soubor projektu by vypadal jako následující:Your project file would look like the following:

a.proja.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <Target Name="Build">
        <MSBuild Projects="a1.sln..." Properties="Configuration=Release;
          Architecture=x86"/>
        <MSBuild Projects="a2.sln" Properties="Configuration=Release;
          Architecture=ia64"/>
    </Target>
</Project>

Pomocí metadat AdditionalProperties můžete zjednodušit použití jedné úlohy MSBuild pomocí následujících kroků:By using the AdditionalProperties metadata, you can simplify this to use a single MSBuild task by using the following:

a.proja.proj

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <ProjectToBuild Include="a1.sln...">
            <AdditionalProperties>Architecture=x86
              </AdditionalProperties>
        </ProjectToBuild>
        <ProjectToBuild Include="a2.sln">
            <AdditionalProperties>Architecture=ia64
              </AdditionalProperties>
        </ProjectToBuild>
    </ItemGroup>
    <Target Name="Build">
        <MSBuild Projects="@(ProjectToBuild)"
          Properties="Configuration=Release"/>
    </Target>
</Project>

PříkladExample

Následující příklad používá MSBuild úlohu k sestavení projektů určených ProjectReferences kolekcí položek.The following example uses the MSBuild task to build the projects specified by the ProjectReferences item collection. Výsledné výstupní výstupy jsou uloženy v AssembliesBuiltByChildProjects kolekci položek.The resulting target outputs are stored in the AssembliesBuiltByChildProjects item collection.

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

    <ItemGroup>
        <ProjectReferences Include="*.*proj" />
    </ItemGroup>

    <Target Name="BuildOtherProjects">
        <MSBuild
            Projects="@(ProjectReferences)"
            Targets="Build">
            <Output
                TaskParameter="TargetOutputs"
                ItemName="AssembliesBuiltByChildProjects" />
        </MSBuild>
    </Target>

</Project>

Viz takéSee also