Vložené úlohy nástroje MSBuild

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

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

Ve MSBuild 15.8 byl přidán Objekt RoslynCodeTaskFactory, který může .NET Standard vložené úlohy pro více platforem. Pokud potřebujete použít vložené úlohy v .NET Core, musíte použít RoslynCodeTaskFactory.

Struktura vložené úlohy

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

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

Element v příkladu má tři atributy, které popisují úlohu a objekt pro vytváření vložené úlohy, UsingTask který ji zkompiluje.

  • Atribut TaskName název úlohy, v tomto případě DoNothing .

  • Atribut má název třídy, která implementuje objekt pro vytváření TaskFactory vložené úlohy.

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

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

  • Element ParameterGroup je volitelný. Pokud je 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.

  • Element Task popisuje a obsahuje zdrojový kód úlohy.

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

  • Element Using vypíše obory názvů, ke které chcete získat přístup. Tento příkaz se Using podobá příkazu v jazyce Visual C#. Atribut Namespace určuje obor názvů, který se má zahrnout.

Reference Prvky Using a jsou jazykové. Vložené úlohy mohou být napsány v libovolném z podporovaných jazyků .NET CodeDom, například v Visual Basic nebo Visual C#.

Poznámka

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

Element kódu

Poslední podřízený prvek, který se má v Task elementu objevit, je Code element . Element Code obsahuje nebo vyhledá kód, který chcete zkompilovat do úlohy. To, co jste vložili do elementu, závisí na Code tom, jak chcete úlohu napsat.

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

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

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

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

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

Samotný kód se obvykle zobrazuje mezi <![CDATA[ značkou a ]]> značkou. Vzhledem k tomu, že se kód nachází v oddílu CDATA, nemusíte se starat o ukončování rezervovaných znaků, například <" or "> " ".

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

Poznámka

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

Helloworld

Tady je robustnější vložený úkol. Úloha HelloWorld zobrazí text "Hello, world!" na výchozím zařízení pro protokolování chyb, což je obvykle systémová konzola nebo okno Visual Studio výstupu. Element 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>

Úlohu HelloWorld můžete uložit do souboru s názvem HelloWorld.targets a potom 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 úlohy jsou podřízené prvky ParameterGroup elementu. Každý parametr přebírá název elementu, který ho definuje. Následující kód definuje parametr Text .

<ParameterGroup>
  <Text />
</ParameterGroup>

Parametry mohou mít jeden nebo více z těchto atributů:

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

  • 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žkou, nebo hodnotou, kterou lze převést na řetězec a z něj pomocí system.Convert.ChangeType. (Jinými slovy, jakýkoli typ, který lze předat do a z externí úlohy.)

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

Třeba

<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 má Code element atribut nebo , vytvoří se vlastnosti automaticky pro každý Type Fragment Method parametr. Jinak musí být vlastnosti explicitně deklarovány ve zdrojovém kódu úlohy a musí přesně odpovídat definicím jejich parametrů.

Příklad

Následující vložený úkol 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>

Viz také