Share via

Vložené úlohy nástroje MSBuild

  • Článek

Úlohy NÁSTROJE MSBuild jsou obvykle vytvořeny kompilací třídy, která implementuje ITask rozhraní. Další informace najdete v tématu Úkoly.

Počínaje rozhraním .NET Framework verze 4 můžete v souboru projektu vytvářet úkoly vložené do souboru projektu. Pro hostování úlohy nemusíte vytvářet samostatné sestavení. To usnadňuje sledování zdrojového kódu a usnadňuje nasazení úlohy. Zdrojový kód je integrovaný do skriptu.

V MSBuild 15.8 byl přidán RoslynCodeTaskFactory. Pro aktuální vývoj nezapomeňte použít RoslynCodeTaskFactory, nikoli CodeTaskFactory. CodeTaskFactory podporuje pouze verze jazyka C# až 4.0.

Struktura vloženého úkolu

Vložený úkol je obsažen Pomocí UsingTask elementu. Vložený úkol a UsingTask prvek, který ho obsahuje, jsou obvykle zahrnuty do souboru .targets a podle potřeby importovány do jiných souborů projektu. Tady je základní vložený úkol. Všimněte si, že nic nedělá.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- This simple inline task does nothing. -->
  <UsingTask
    TaskName="DoNothing"
    TaskFactory="CodeTaskFactory"
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >
    <ParameterGroup />
    <Task>
      <Reference Include="" />
      <Using Namespace="" />
      <Code Type="Fragment" Language="cs">
      </Code>
    </Task>
  </UsingTask>
</Project>

Prvek UsingTask v příkladu má tři atributy, které popisují úkol a vloženou úlohu továrnu, která ji zkompiluje.

  • Atribut TaskName v tomto případě DoNothingpojmenuje úkol .

  • Atributy TaskFactory pojmenují třídu, která implementuje vloženou úlohu factory.

  • Atribut AssemblyFile poskytuje umístění vloženého objektu pro vytváření úloh. Alternativně můžete pomocí atributu AssemblyName zadat plně kvalifikovaný název vložené třídy objektu pro vytváření úloh, která je obvykle umístěna v $(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll.

Zbývající prvky DoNothing úkolu jsou prázdné a jsou k dispozici pro ilustraci pořadí a struktury vloženého úkolu. Robustnější příklad je uveden dále v tomto tématu.

  • Prvek ParameterGroup je nepovinný. Při zadání deklaruje parametry pro úlohu. Další informace o vstupních a výstupních parametrech najdete v části Vstupní a výstupní parametry dále v tomto tématu.

  • Prvek Task popisuje a obsahuje zdrojový kód úkolu.

  • Element Reference určuje odkazy na sestavení .NET, která používáte v kódu. To je ekvivalentem přidání odkazu na projekt v sadě Visual Studio. Atribut Include určuje cestu odkazovaného sestavení.

  • Tento Using prvek obsahuje seznam oborů názvů, ke kterým chcete získat přístup. Podobá se Using tomu příkaz v jazyce Visual C#. Atribut Namespace určuje obor názvů, který se má zahrnout.

Reference a Using prvky jsou nezávislé na jazyce. Vložené úlohy lze psát v některém z podporovaných jazyků .NET CodeDom, například v jazyce Visual Basic nebo Visual C#.

Poznámka:

Prvky obsažené v elementu Task jsou specifické pro objekt pro vytváření úloh, v tomto případě objekt pro vytváření úloh kódu.

Prvek kódu

Posledním podřízeným prvkem, který se má objevit uvnitř elementu TaskCode , je element. Prvek Code obsahuje nebo vyhledá kód, který chcete zkompilovat do úkolu. To, co vložíte do elementu Code , závisí na tom, jak chcete napsat úkol.

Atribut Language určuje jazyk, ve kterém je váš kód napsán. Přijatelné hodnoty jsou cs pro jazyk C# vb pro Visual Basic.

Atribut Type určuje typ kódu, který se nachází v elementu Code .

  • Pokud je Classhodnota Type , pak Code prvek obsahuje kód pro třídu, která je odvozena z ITask rozhraní.

  • Pokud je Methodhodnota Type , pak kód definuje přepsání Execute metody ITask rozhraní.

  • Pokud je Fragmenthodnota Type , pak kód definuje obsah Execute metody, ale ne podpis nebo return příkaz.

Samotný kód se obvykle zobrazuje mezi značkou <![CDATA[ a značkou ]]> . Protože kód je v části CDATA, nemusíte se starat o únik vyhrazených znaků, například "<" nebo ">".

Případně můžete pomocí Source atributu Code elementu určit umístění souboru, který obsahuje kód pro váš úkol. Kód ve zdrojovém souboru musí být typu, který je určen atributem Type . Source Pokud atribut existuje, výchozí hodnota Type je Class. Pokud Source není k dispozici, výchozí hodnota je Fragment.

Poznámka:

Při definování třídy úkolu ve zdrojovém souboru musí název třídy souhlasit s TaskName atributem odpovídajícího UsingTask elementu.

Helloworld

Tady je robustnější vložený úkol. Úloha HelloWorld zobrazí "Hello, world!" na výchozím zařízení protokolování chyb, což je obvykle systémová konzola nebo okno Výstup sady Visual Studio. Prvek Reference v příkladu je zahrnut pouze pro ilustraci.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- This simple inline task displays "Hello, world!" -->
  <UsingTask
    TaskName="HelloWorld"
    TaskFactory="CodeTaskFactory"
    AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll" >
    <ParameterGroup />
    <Task>
      <Reference Include="System.Xml"/>
      <Using Namespace="System"/>
      <Using Namespace="System.IO"/>
      <Code Type="Fragment" Language="cs">
<![CDATA[
// Display "Hello, world!"
Log.LogError("Hello, world!");
]]>
      </Code>
    </Task>
  </UsingTask>
</Project>

Úkol HelloWorld můžete uložit do souboru s názvem HelloWorld.targets a pak ho vyvolat z projektu následujícím způsobem.

<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Import Project="HelloWorld.targets" />
  <Target Name="Hello">
    <HelloWorld />
  </Target>
</Project>

Vstupní a výstupní parametry

Vložené parametry úkolu jsou podřízené prvky elementu ParameterGroup . Každý parametr přebírá název prvku, který ho definuje. Následující kód definuje parametr Text.

<ParameterGroup>
  <Text />
</ParameterGroup>

Parametry můžou mít jeden nebo více těchto atributů:

  • Required je volitelný atribut, který je false ve výchozím nastavení. Pokud trueje parametr povinný a musí být před voláním úkolu uvedena hodnota.

  • ParameterType je volitelný atribut, který je System.String ve výchozím nastavení. Může být nastaven na libovolný plně kvalifikovaný typ, který je buď položka nebo hodnota, která lze převést na řetězec pomocí System.Convert.ChangeType. (Jinými slovy, jakýkoli typ, který lze předat externímu úkolu a z externího úkolu.)

  • Output je volitelný atribut, který je false ve výchozím nastavení. Pokud true, pak parametr musí být před vrácením z Execute metoda.

Příklad:

<ParameterGroup>
  <Expression Required="true" />
  <Files ParameterType="Microsoft.Build.Framework.ITaskItem[]" Required="true" />
  <Tally ParameterType="System.Int32" Output="true" />
</ParameterGroup>

definuje tyto tři parametry:

  • Expression je povinný vstupní parametr typu System.String.

  • Files je povinný vstupní parametr seznamu položek.

  • Tally je výstupní parametr typu System.Int32.

Pokud prvek Code má Type atribut Fragment nebo Method, vlastnosti jsou automaticky vytvořeny pro každý parametr. V opačném případě musí být vlastnosti explicitně deklarovány ve zdrojovém kódu úlohy a musí přesně odpovídat jejich definici parametrů.

Příklad

Následující vložená úloha nahradí každý výskyt tokenu v daném souboru danou hodnotou.

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

  <UsingTask TaskName="TokenReplace" TaskFactory="CodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll">
    <ParameterGroup>
      <Path ParameterType="System.String" Required="true" />
      <Token ParameterType="System.String" Required="true" />
      <Replacement ParameterType="System.String" Required="true" />
    </ParameterGroup>
    <Task>
      <Code Type="Fragment" Language="cs"><![CDATA[
string content = File.ReadAllText(Path);
content = content.Replace(Token, Replacement);
File.WriteAllText(Path, content);

]]></Code>
    </Task>
  </UsingTask>

  <Target Name='Demo' >
    <TokenReplace Path="C:\Project\Target.config" Token="$MyToken$" Replacement="MyValue"/>
  </Target>
</Project>

Související obsah