Referenční dokumentace pro použití nástroje MSBuild v příkazovém řádku

Článek
11/01/2024

Při použití MSBuild.exe k sestavení projektu nebo souboru řešení můžete zahrnout několik přepínačů, které určují různé aspekty procesu.

Každý přepínač je k dispozici ve dvou formách: -switch a /switch. V dokumentaci se -switch zobrazí jenom formulář. Přepínače nerozlišují malá a velká písmena. Pokud spustíte nástroj MSBuild z jiného prostředí než příkazového řádku Windows, můžou seznamy argumentů přepínače (oddělené středníky nebo čárkami) potřebovat jednoduché nebo dvojité uvozovky, aby se zajistilo, že seznamy se předávají nástroji MSBuild místo interpretace prostředím.

Příkazy rozhraní příkazového řádku .NET CLI dotnet build, dotnet publish, dotnet msbuild a související příkazy předávají tyto přepínače do nástroje MSBuild, takže tento odkaz lze použít při použití těchto příkazů, ale dotnet run ne.

Syntaxe

MSBuild.exe [Switches] [ProjectFile]

Argumenty

Argument	Popis
`ProjectFile`	Sestaví cíle v zadaném souboru projektu. Pokud nezadáte soubor projektu, nástroj MSBuild vyhledá v aktuálním pracovním adresáři příponu názvu souboru, která končí příponou proj a použije tento soubor. Pro tento argument můžete také zadat soubor řešení sady Visual Studio.

přepínače,

První sloupec v následující tabulce zobrazuje dlouhý a krátký tvar každého přepínače. Obě formy jsou ekvivalentní.

Hranaté závorky [] označují volitelné části a složené závorky {}označují hodnoty zadané uživatelem.

Přepínač	Popis
`-detailedSummary[:{True or False}]` `-ds[:{True or False}]`	Pokud `True`, zobrazí podrobné informace na konci protokolu sestavení o konfiguracích, které byly vytvořeny a jak byly naplánovány na uzly.
`-getItem:{itemName,...}`	Po vyhodnocení zapište hodnotu položky nebo položek, aniž byste provedli sestavení, nebo pokud `-targets` se použije možnost nebo `-getTargetResult` možnost, zapište hodnoty za sestavením.
`-getProperty:{propertyName,...}`	Po vyhodnocení zapište hodnotu vlastnosti nebo vlastností, aniž byste provedli sestavení, nebo pokud `-targets` se použije možnost nebo `-getTargetResult` možnost, zapište hodnoty za sestavením.
`-getTargetResult:{targetName,...}`	Zapište výstupní hodnoty zadaných cílů.
`-graphBuild[:{True or False}]` `-graph[:{True or False}]`	Způsobí, že nástroj MSBuild sestaví a sestaví graf projektu. Vytvoření grafu zahrnuje identifikaci odkazů projektu na závislosti formuláře. Sestavení grafu zahrnuje pokus o sestavení odkazů projektu před projekty, které na ně odkazují, a liší se od tradičního plánování nástroje MSBuild. Vyžaduje MSBuild 16 nebo novější.
`-help` `/?` nebo `-h`	Zobrazení informací o využití Následující příkaz je příkladem: `msbuild.exe -?`
`-ignoreProjectExtensions: {extensions}` `-ignore: {extensions}`	Při určování souboru projektu, který se má sestavit, ignorujte zadaná rozšíření. Středník nebo čárka slouží k oddělení více rozšíření, jak ukazuje následující příklad: `-ignoreprojectextensions:.vcproj,.sln`
`-inputResultsCaches[:{cacheFile; ...}]` `-irc[:{cacheFile; ...}]`	Středník oddělený seznam souborů vstupní mezipaměti, ze kterých msBuild načte výsledky sestavení. Pokud `-isolateProjects` je nastavena na `False`, nastaví se na `True`.
`-interactive[:{True or False}]`	Označuje, že akce v sestavení mají povolenou interakci s uživatelem. Nepoužívejte tento argument v automatizovaném scénáři, kdy se neočekává interaktivita. `-interactive` Určení je stejné jako určení `-interactive:true`. Pomocí parametru můžete přepsat hodnotu, která pochází ze souboru odpovědi.
`-isolateProjects[:{True, MessageUponIsolationViolation, False}]` `-isolate[:{True, MessageUponIsolationViolation, False}]`	Způsobí, že nástroj MSBuild sestaví každý projekt izolovaně. Pokud je nastavena hodnota `MessageUponIsolationViolation` (nebo její krátká forma `Message`), jsou při zadání přepínače serializovány `-outputResultsCache` pouze výsledky z cílů nejvyšší úrovně. Tato možnost je zmírnit riziko porušení cíle izolace na projektu závislostí s nesprávným stavem kvůli závislosti na cíli uloženém v mezipaměti, jehož vedlejší účinky by se nebraly v úvahu. (Například definice vlastnosti.) Tento režim je více omezující, protože vyžaduje, aby byl graf projektu staticky zjistitelný v době vyhodnocení, ale může zlepšit plánování a snížit režii paměti při sestavování velké sady projektů.
`-lowPriority[:{True or False}]` `-low[:{True or False}]`	Způsobí spuštění nástroje MSBuild s nízkou prioritou procesu. `-lowPriority` Určení je stejné jako určení `-lowPriority:True`.
`-maxCpuCount[:{number}]` `-m[:{number}]`	Určuje maximální počet souběžnýchprocesůch Pokud tento přepínač nezadáte, výchozí hodnota je 1. Pokud tento přepínač zahrnete bez zadání hodnoty, nástroj MSBuild použije až počet procesorů v počítači. Další informace naleznete v tématu Paralelní sestavování více projektů. Následující příklad dává nástroji MSBuild pokyn k sestavení pomocí tří procesů MSBuild, které umožňují sestavení tří projektů najednou: `msbuild myproject.proj -maxcpucount:3`
`-noAutoResponse` `-noautorsp`	Nezahrnujte automaticky žádné soubory MSBuild.rsp nebo Directory.Build.rsp .
`-nodeReuse:{value}` `-nr:{value}`	Povolte nebo zakažte opakované použití uzlů NÁSTROJE MSBuild. Můžete určit tyto hodnoty: - Pravda. Uzly zůstanou po dokončení sestavení, aby je následné buildy mohly používat (výchozí). - Nepravda. Uzly po dokončení sestavení nezůstanou. Uzel odpovídá projektu, který se spouští. Pokud zahrnete `-maxcpucount` přepínač, může se spustit více uzlů současně.
`-nologo`	Nezobrazovat úvodní banner ani zprávu o autorských právech.
`-preprocess[:{filepath}]` `-pp[:{filepath}]`	Vytvořte jeden agregovaný soubor projektu vložením všech souborů, které by se naimportovaly během sestavení, s označenými hranicemi. Pomocí tohoto přepínače můžete snadněji určit, které soubory se importují, odkud se soubory importují a které soubory přispívají k sestavení. Pokud použijete tento přepínač, projekt není sestavený. Pokud zadáte , `filepath`agregovaný soubor projektu je výstupem souboru. V opačném případě se výstup zobrazí v okně konzoly. Informace o tom, jak pomocí elementu `Import` vložit soubor projektu do jiného souboru projektu, naleznete v tématu Import element (MSBuild) a Postupy: Použití stejného cíle v několika souborech projektu.
`-outputResultsCache[:{cacheFile}]` `-orc[:{cacheFile}]`	Výstupní soubor mezipaměti, kde NÁSTROJ MSBuild zapisuje obsah jeho výsledků sestavení do mezipaměti na konci sestavení. Pokud `-isolateProjects` je nastavena na `False`, nastaví se na `True`.
`profileEvaluation:{file}`	Profily vyhodnocení nástroje MSBuild a zapíše výsledek do zadaného souboru. Pokud je přípona zadaného souboru .md, výsledek se vygeneruje ve formátu Markdown. V opačném případě se vytvoří soubor oddělený tabulátorem.
`-property:{name}={value}` `-p:{name}={value}`	Nastavte nebo přepište zadané vlastnosti na úrovni projektu, kde `name` je název vlastnosti a `value` je hodnota vlastnosti. Zadejte každou vlastnost samostatně, nebo pomocí středníku nebo čárky oddělte více vlastností, jak ukazuje následující příklad: `-property:WarningLevel=2;OutDir=bin\Debug` Seznam běžně používaných vlastností projektu naleznete v části Společné vlastnosti projektu MSBuild. Úplná sada dostupných vlastností závisí na typu projektu, sadě SDK a importovaných souborech.
`-restore` `-r`	`Restore` Spustí cíl před sestavením skutečných cílů.
`-restoreProperty:{name}={value}` `-rp:{name}={value}`	Nastavte nebo přepište tyto vlastnosti na úrovni projektu pouze během obnovení a nepoužívejte vlastnosti zadané v argumentu `-property` . `name` je název vlastnosti a `value` je hodnota vlastnosti. Pomocí středníku nebo čárky oddělte více vlastností nebo zadejte každou vlastnost zvlášť.
`-target:{targets}` `-t:{targets}`	Sestavte zadané cíle v projektu. Zadejte každý cíl samostatně nebo použijte středník nebo čárku k oddělení více cílů, jak ukazuje následující příklad: `-target:PrepareResources;Compile` Pokud pomocí tohoto přepínače zadáte nějaké cíle, spustí se místo cílů v `DefaultTargets` atributu v souboru projektu. Další informace naleznete v tématu Pořadí sestavení cíle a Postupy: Určení cíle, který se má sestavit jako první. Cíl je skupina úkolů. Další informace naleznete v tématu Cíle.
`-targets[:{file}]` `-ts[:{file}]`	Zapište seznam dostupných cílů do zadaného souboru (nebo do výstupního zařízení, pokud není zadaný žádný soubor), aniž byste skutečně spouštěli proces sestavení.
`-toolsVersion:{version}` `-tv:{version}`	Určuje vlastní sadu nástrojů. Sada nástrojů se skládá z úloh, cílů a nástrojů, které se používají k sestavení aplikace. Viz Sada nástrojů (ToolsVersion) a Standardní a vlastní konfigurace sady nástrojů.
`-validate:[{schema}]` `-val[{schema}]`	Ověřte soubor projektu a v případě úspěšného ověření projekt sestavte. Pokud ho nezadáte `schema`, projekt se ověří ve výchozím schématu. Pokud zadáte `schema`, projekt se ověří podle zadaného schématu. Následující nastavení je příkladem: `-validate:MyExtendedBuildSchema.xsd`
`-verbosity:{level}` `-v:{level}`	Určuje množství informací, které se mají zobrazit v protokolu sestavení. Každý protokolovací zařízení zobrazuje události na základě úrovně podrobností, kterou jste pro tento protokolovač nastavili. Můžete zadat následující úrovně podrobností: `q[uiet]`, `m[inimal]`, ( `n[ormal]` výchozí), `d[etailed]`a `diag[nostic]`. Následující nastavení je příkladem: `-verbosity:quiet`
`-version` `-ver`	Zobrazí pouze informace o verzi. Projekt není sestaven.
`@{file}`	Vložte přepínače příkazového řádku z textového souboru. Pokud máte více souborů, zadáte je samostatně. Další informace najdete v tématu Soubory odpovědí.
`-warnAsError[:{code; ...}]` `-err[:{code; ...}]`	Seznam kódů upozornění, které se mají považovat za chyby K oddělení více kódů upozornění použijte středník nebo čárku. Pokud chcete všechna upozornění považovat za chyby, použijte přepínač bez hodnot. Když se upozornění považuje za chybu, cíl se bude dál spouštět, jako by se jednalo o upozornění, ale celkové sestavení selže. Příklad: `-err:MSB4130`
`-warnNotAsError[:{code; ...}]` `-noerr[:{code; ...}]`	MSBuild 17.0 a novější. Seznam kódů upozornění, které by neměly být povýšeny na chyby. Konkrétně pokud je přepínač warnAsError nastavený tak, aby se upřednostňovala všechna upozornění na chyby, kódy chyb zadané funkcí warnNotAsError nejsou povýšeny. To nemá žádný vliv, pokud není chyba warnAsError nastavená tak, aby upřednostňovala všechna upozornění na chyby. K oddělení více kódů upozornění použijte středník nebo čárku. Příklad: `-noerr:MSB4130`
`-warnAsMessage[:{code}; ...}]` `-noWarn[:{code; ...}]`	Seznam kódů upozornění, které se mají považovat za zprávy s nízkou důležitostí K oddělení více kódů upozornění použijte středník nebo čárku. Příklad: `-noWarn:MSB3026`

Přepínače pro protokolovací nástroje

Přepínač	Popis
`-binaryLogger[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]` `-bl[:[LogFile=]{output.binlog}` `[;ProjectImports=None`,`Embed`,`ZipFile]]`	Serializuje všechny události sestavení do komprimovaného binárního souboru. Ve výchozím nastavení je soubor v aktuálním adresáři a má název msbuild.binlog. Binární protokol je podrobný popis procesu sestavení, který lze později použít k rekonstrukci textových protokolů a použití jinými analytickými nástroji. Binární protokol je obvykle 10–20x menší než nejpodrobnější protokol na úrovni diagnostiky textu, ale obsahuje další informace. Binární protokolovací nástroj ve výchozím nastavení shromažďuje zdrojový text souborů projektu, včetně všech importovaných projektů a cílových souborů, ke kterým došlo během sestavení. `ProjectImports` Volitelné parametry řídí toto chování: - ProjectImports=None. Neshromažďujte importy projektu. - ProjectImports=Embed. Vložení importů projektu do souboru protokolu (výchozí) - ProjectImports=ZipFile. Uložte soubory projektu do {output}.projectimports.zip , kde <je výstup> stejný název jako název souboru binárního protokolu. Výchozí nastavení pro ProjectImports je Vložit. Poznámka: Protokolovací nástroj neshromažďuje zdrojové soubory, jako `.cs`je například , `.cpp`atd. Soubor .binlog se dá přehrát tak, že ho předáte msbuild.exe jako argument místo projektu nebo řešení. Ostatní protokolovací nástroje obdrží informace obsažené v souboru protokolu, jako by došlo k původnímu sestavení. Další informace o binárním protokolu a jeho využití najdete tady: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md Příklady: - `-bl` - `-bl:output.binlog` - `-bl:output.binlog;ProjectImports=None` - `-bl:output.binlog;ProjectImports=ZipFile` - `-bl:..\..\custom.binlog` - `-binaryLogger`
`-consoleLoggerParameters:{parameters}` `-clp:{parameters}`	Předejte parametry, které zadáte do protokolovacího nástroje konzoly, který zobrazí informace o sestavení v okně konzoly. Můžete zadat následující parametry: - PerformanceSummary. Zobrazí čas strávený v úkolech, cílech a projektech. - Souhrn. Zobrazení souhrnu chyb a upozornění na konci - NoSummary. Na konci se nezobrazuje souhrn chyb a upozornění. - ChybyOnly. Zobrazit pouze chyby. - WarningsOnly. Zobrazí se jenom upozornění. - NoItemAndPropertyList. Nezobrazovat seznam položek a vlastností, které by se zobrazily na začátku každého sestavení projektu, pokud je úroveň podrobností nastavena na `diagnostic`hodnotu . - ShowCommandLine. Umožňuje zobrazit `TaskCommandLineEvent` zprávy. - ShowProjectFile. Umožňuje zobrazit cestu k souboru projektu v diagnostických zprávách. Toto nastavení je ve výchozím nastavení zapnuté. - ShowTimestamp. Zobrazí časové razítko jako předponu jakékoli zprávy. - ShowEventId. Zobrazí ID události pro každou spuštěnou událost, dokončenou událost a zprávu. - ForceNoAlign. Nezarovnávejte text na velikost vyrovnávací paměti konzoly. - DisableConsoleColor. Pro všechny zprávy protokolování použijte výchozí barvy konzoly. - Zakázání protokoluMPLogging Zakažte styl protokolování víceprocesoru výstupu při spuštění v režimu bez multiprocesoru. - EnableMPLogging. Povolte styl protokolování multiprocesoru i při spuštění v režimu bez víceprocesoru. Tento styl protokolování je ve výchozím nastavení zapnutý. - ForceConsoleColor. Barvy konzoly ANSI používejte, i když ji konzola nepodporuje. - Podrobnosti. `-verbosity` Přepište nastavení tohoto protokolovacího nástroje. Středník slouží k oddělení více parametrů, jak ukazuje následující příklad: `-consoleloggerparameters:PerformanceSummary;NoSummary -verbosity:minimal` Výchozí protokolovací služba konzoly je v normálních podrobnostech a obsahuje `Summary`.
`-distributedFileLogger` `-dfl`	Zapíše výstup sestavení každého uzlu MSBuild do vlastního souboru. Počátečním umístěním těchto souborů je aktuální adresář. Ve výchozím nastavení se soubory nazývají MSBuild{NodeId}.log. Přepínač můžete použít `-fileLoggerParameters` k určení umístění souborů a dalších parametrů pro fileLogger. Pokud soubor protokolu pojmenujete pomocí přepínače, distribuovaný `-fileLoggerParameters` protokolovací modul použije tento název jako šablonu a při vytváření souboru protokolu pro každý uzel připojí ID uzlu.
`-distributedLogger:{central logger},{forwarding logger}, ...` `-dl:{central logger},{forwarding logger, ...}`	Protokolování událostí z nástroje MSBuild a připojení jiné instance protokolovacího nástroje ke každému uzlu Chcete-li zadat více protokolovacích zařízení, zadejte každý protokolovací počítač samostatně. Syntaxe protokolovacího nástroje slouží k určení protokolovacího nástroje, s výjimkou toho, že zadáte a další třídu pro předávací protokolovací nástroj. Syntaxi protokolovacího nástroje najdete v přepínači `-logger` . Následující příklady ukazují, jak tento přepínač použít: `-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral` `-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll`
`-fileLogger[{number}]` `-fl[{number}]`	Zapište výstup sestavení do jednoho souboru v aktuálním adresáři. Pokud ho nezadáte `number`, bude výstupní soubor pojmenován msbuild.log. Pokud zadáte `number`, výstupní soubor má název msbuild<n>.log, kde <n> je `number`. `Number` může být číslice od 1 do 9. Přepínač můžete použít `-fileLoggerParameters` k určení umístění souboru a dalších parametrů pro fileLogger.
`-fileLoggerParameters[{number}]:` `parameters` `-flp[{number}]: {parameters}`	Určuje všechny další parametry pro protokolovací nástroj souborů a distribuovaný protokolovací nástroj souborů. Přítomnost tohoto přepínače znamená, že je k dispozici odpovídající `-filelogger[number]` přepínač. `Number` může být číslice od 1 do 9. Můžete použít všechny parametry, které jsou uvedeny pro `-consoleloggerparameters`. Můžete také použít jeden nebo více následujících parametrů: - LogFile. Cesta k souboru protokolu, do kterého se zapisuje protokol sestavení. Distribuovaný protokolovací program předpony této cesty k názvům souborů protokolu. - Připojit. Určuje, zda je protokol sestavení připojen k souboru protokolu nebo jej přepíše. Když nastavíte přepínač, protokol sestavení se připojí k souboru protokolu. Pokud přepínač není k dispozici, obsah existujícího souboru protokolu se přepíše. Příklad: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append` Pokud zahrnete explicitní `true` nebo `false` nastavení, protokol se připojí bez ohledu na nastavení. Pokud přepínač připojení nezadáte, protokol se přepíše. V tomto případě se soubor přepíše: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log` V tomto případě se soubor připojí: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true` V tomto případě se soubor připojí: `msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=false` - Kódování. Určuje kódování souboru (například UTF-8, Unicode nebo ASCII). Následující příklad vygeneruje samostatné soubory protokolu pro upozornění a chyby: `-flp1:logfile=errors.txt;errorsonly -flp2:logfile=warnings.txt;warningsonly` Následující příklady ukazují další možnosti: `-fileLoggerParameters:LogFile=MyLog.log;Append; Verbosity=diagnostic;Encoding=UTF-8` `-flp:Summary;Verbosity=minimal;LogFile=msbuild.sum` `-flp1:warningsonly;logfile=msbuild.wrn` `-flp2:errorsonly;logfile=msbuild.err`
`-logger:logger` `-l:logger`	Určuje protokolovací nástroj, který se má použít k protokolování událostí z nástroje MSBuild. Chcete-li zadat více protokolovacích zařízení, zadejte každý protokolovací počítač samostatně. `logger`Pro:`[LoggerClass,]LoggerAssembly[;LoggerParameters]` `LoggerClass`Pro:`[PartialOrFullNamespace.]LoggerClassName` Pokud sestavení obsahuje přesně jeden protokolovací objekt, nemusíte zadávat třídu loggeru. `LoggerAssembly`Pro:`AssemblyName[,StrongName] \\| AssemblyFile` Parametry protokolovacího nástroje jsou volitelné a předávají se do protokolovacího nástroje přesně tak, jak je zadáte. Následující příklady používají `-logger` přepínač. `-logger:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral` `-logger:XMLLogger,C:\Loggers\MyLogger.dll;OutputAsHTML`
`-noConsoleLogger` `-noconlog`	Zakažte výchozí protokolovací nástroje konzoly a nezaznamujte události do konzoly.
`-terminalLogger[:auto`,`on`,`off]` `-tl[:auto`,`on`,`off]`	Povolte nebo zakažte protokolovací funkci terminálu. Protokolovací modul terminálu poskytuje vylepšený výstup sestavení v konzole v reálném čase, uspořádaný logicky podle projektu a navržený tak, aby zvýrazňoval informace umožňující akce. Zadejte `auto` (nebo použijte možnost bez argumentů) k použití protokolovacího nástroje terminálu pouze v případě, že standardní výstup není přesměrován. Neanalyzovat výstup nebo jinak spoléhat na zbývající změny v budoucích verzích. Tato možnost je dostupná ve verzi MSBuild 17.8 a novější.

Příklad 1

Následující příklad sestaví rebuild cíl projektu MyProject.proj .

MSBuild.exe MyProject.proj -t:rebuild

Příklad 2

K provádění složitějších sestavení můžete použít MSBuild.exe . Můžete ho například použít k sestavení konkrétních cílů konkrétních projektů v řešení. Následující příklad znovu sestaví projekt NotInSolutionFolder a vyčistí projekt InSolutionFolder, který je ve složce řešení NewFolder .

msbuild SlnFolders.sln -t:NotInSolutionfolder:Rebuild;NewFolder\InSolutionFolder:Clean

Sdílet prostřednictvím