Udostępnij za pośrednictwem

Dokumentacja wiersza polecenia programu MSBuild

  • Artykuł

Jeśli używasz MSBuild.exe do kompilowania pliku projektu lub rozwiązania, możesz dołączyć kilka przełączników, aby określić różne aspekty procesu.

Każdy przełącznik jest dostępny w dwóch formach: -switch i /switch. W dokumentacji jest wyświetlany -switch tylko formularz. Przełączniki nie są uwzględniane wielkości liter. Jeśli uruchomisz program MSBuild z powłoki innej niż wiersz polecenia systemu Windows, listy argumentów do przełącznika (oddzielone średnikami lub przecinkami) mogą wymagać pojedynczych lub podwójnych cudzysłowów, aby upewnić się, że listy są przekazywane do programu MSBuild zamiast interpretować przez powłokę.

Polecenia interfejsu wiersza polecenia platformy .NET dotnet build, dotnet publish, dotnet msbuild i powiązane polecenia przekazują te przełączniki do programu MSBuild, więc to odwołanie ma zastosowanie w przypadku używania tych poleceń.dotnet run

Składnia

MSBuild.exe [Switches] [ProjectFile]

Argumenty

Argument opis
ProjectFile Tworzy obiekty docelowe w określonym pliku projektu. Jeśli nie określisz pliku projektu, program MSBuild przeszukuje bieżący katalog roboczy dla rozszerzenia nazwy pliku, które kończy się na pliku proj i używa tego pliku. Można również określić plik rozwiązania programu Visual Studio dla tego argumentu.

Switches (Układy samoczynnego załączania)

Pierwsza kolumna w poniższej tabeli przedstawia długą i krótką formę każdego przełącznika. Oba formularze są odpowiednikami.

Nawiasy kwadratowe wskazują opcjonalne części, a nawiasy [] klamrowe {}wskazują wartości dostarczone przez użytkownika.

Switch opis
-detailedSummary[:{True or False}]

-ds[:{True or False}]		 Jeśli Trueprogram pokaże szczegółowe informacje na końcu dziennika kompilacji dotyczące konfiguracji, które zostały skompilowane i jak zostały zaplanowane do węzłów.
-getItem:{itemName,...} Zapisz wartość elementu lub elementów po ocenie, bez wykonywania kompilacji lub jeśli -targets jest używana opcja lub opcja, -getTargetResult zapisz wartości po kompilacji.
-getProperty:{propertyName,...} Zapisz wartość właściwości lub właściwości po ocenie, bez wykonywania kompilacji lub jeśli -targets jest używana opcja lub -getTargetResult opcja, zapisz wartości po kompilacji.
-getTargetResult:{targetName,...} Zapisz wartości wyjściowe określonych obiektów docelowych.
-graphBuild[:{True or False}]

-graph[:{True or False}]		 Powoduje utworzenie i skompilowanie grafu projektu przez program MSBuild. Konstruowanie grafu obejmuje identyfikowanie odwołań do projektu w celu utworzenia zależności. Kompilowanie tego grafu obejmuje próbę skompilowania odwołań projektu przed projektami odwołującymi się do nich, różniąc się od tradycyjnego planowania programu MSBuild. Wymaga programu MSBuild 16 lub nowszego.
-help

/? lub -h		 Wyświetl informacje o użyciu. Następujące polecenie jest przykładem:

msbuild.exe -?
-ignoreProjectExtensions: {extensions}

-ignore: {extensions}		 Ignoruj określone rozszerzenia podczas określania pliku projektu do skompilowania. Użyj średnika lub przecinka, aby oddzielić wiele rozszerzeń, jak pokazano w poniższym przykładzie:

-ignoreprojectextensions:.vcproj,.sln
-inputResultsCaches[:{cacheFile; ...}]

-irc[:{cacheFile; ...}]		 Rozdzielona średnikami lista plików pamięci podręcznej danych wejściowych, z których program MSBuild odczytuje wyniki kompilacji. Jeśli -isolateProjects ustawiono wartość False, spowoduje to ustawienie wartości True.
-interactive[:{True or False}] Wskazuje, że akcje w kompilacji mogą wchodzić w interakcje z użytkownikiem. Nie używaj tego argumentu w zautomatyzowanym scenariuszu, w którym nie można oczekiwać interakcyjności. Określanie -interactive parametru jest takie samo, jak określanie -interactive:truewartości . Użyj parametru , aby zastąpić wartość pochodzącą z pliku odpowiedzi.
-isolateProjects[:{True, MessageUponIsolationViolation, False}]

-isolate[:{True, MessageUponIsolationViolation, False}]		 Powoduje, że program MSBuild tworzy każdy projekt w izolacji. W przypadku ustawienia wartości MessageUponIsolationViolation (lub jego krótkiej formy Message) tylko wyniki z celów najwyższego poziomu są serializowane, jeśli -outputResultsCache przełącznik jest dostarczany. Ta opcja polega na ograniczeniu prawdopodobieństwa naruszenia izolacji celu w projekcie zależności przy użyciu nieprawidłowego stanu ze względu na zależność od buforowanego celu, którego skutki uboczne nie zostaną uwzględnione. (Na przykład definicja właściwości). Ten tryb jest bardziej restrykcyjny, ponieważ wymaga, aby wykres projektu był statycznie wykrywalny w czasie oceny, ale może poprawić planowanie i zmniejszyć obciążenie pamięci podczas tworzenia dużego zestawu projektów.
-lowPriority[:{True or False}]

-low[:{True or False}]		 Powoduje uruchomienie programu MSBuild z niskim priorytetem procesu. Określanie -lowPriority parametru jest takie samo, jak określanie -lowPriority:Truewartości .
-maxCpuCount[:{number}]

-m[:{number}]		 Określa maksymalną liczbę współbieżnych procesów do użycia podczas kompilowania. Jeśli ten przełącznik nie zostanie uwzględniony, wartość domyślna to 1. Jeśli dołączysz ten przełącznik bez określenia wartości, program MSBuild używa maksymalnie liczby procesorów na komputerze. Aby uzyskać więcej informacji, zobacz Tworzenie wielu projektów równolegle.

Poniższy przykład instruuje program MSBuild, aby kompilował przy użyciu trzech procesów MSBuild, co pozwala na kompilowanie trzech projektów w tym samym czasie:

msbuild myproject.proj -maxcpucount:3
-noAutoResponse

-noautorsp		 Nie dołączaj automatycznie żadnych plików MSBuild.rsp ani Directory.Build.rsp .
-nodeReuse:{value}

-nr:{value}		 Włącz lub wyłącz ponowne użycie węzłów MSBuild. Można określić następujące wartości:

- Prawda. Węzły pozostają po zakończeniu kompilacji, aby kolejne kompilacje mogły ich używać (wartość domyślna).
- Fałsz. Węzły nie pozostają po zakończeniu kompilacji.

Węzeł odpowiada projektowi, który jest wykonywany. Jeśli przełącznik zostanie -maxcpucount uwzględniony, wiele węzłów może być wykonywanych współbieżnie.
-nologo Nie wyświetlaj baneru startowego ani wiadomości o prawach autorskich.
-preprocess[:{filepath}]

-pp[:{filepath}]		 Utwórz pojedynczy, zagregowany plik projektu, określając wszystkie pliki, które zostaną zaimportowane podczas kompilacji, z oznaczonymi granicami. Za pomocą tego przełącznika można łatwiej określić, które pliki są importowane, skąd są importowane pliki i które pliki współtworzyją kompilację. W przypadku korzystania z tego przełącznika projekt nie jest kompilowany.

Jeśli określisz filepathplik , zagregowany plik projektu będzie zwracany do pliku. W przeciwnym razie dane wyjściowe pojawią się w oknie konsoli.

Aby uzyskać informacje na temat sposobu użycia Import elementu w celu wstawienia pliku projektu do innego pliku projektu, zobacz Import element (MSBuild) i How to: Use the same target in multiple project files (Importowanie elementu (MSBuild) i How to: Use the same target in multiple project files (Jak używać tego samego obiektu docelowego w wielu plikach projektu).
-outputResultsCache[:{cacheFile}]

-orc[:{cacheFile}]		 Plik wyjściowej pamięci podręcznej, w którym program MSBuild zapisuje zawartość pamięci podręcznej wyników kompilacji na końcu kompilacji. Jeśli -isolateProjects ustawiono wartość False, spowoduje to ustawienie wartości True.
profileEvaluation:{file} Profile oceny MSBuild i zapisuje wynik do określonego pliku. Jeśli rozszerzenie określonego pliku to '.md', wynik jest generowany w formacie Markdown. W przeciwnym razie jest generowany plik rozdzielony tabulatorami.
-property:{name}={value}

-p:{name}={value}		 Ustaw lub przesłoń określone właściwości na poziomie projektu, gdzie name jest nazwą właściwości i value jest wartością właściwości. Określ każdą właściwość oddzielnie lub użyj średnika lub przecinka, aby oddzielić wiele właściwości, jak pokazano w poniższym przykładzie:

-property:WarningLevel=2;OutDir=bin\Debug

Zobacz Typowe właściwości projektu MSBuild, aby uzyskać listę często używanych właściwości. Pełny zestaw dostępnych właściwości zależy od typu projektu, zestawu SDK i zaimportowanych plików.
-restore

-r		 Uruchamia element docelowy Restore przed utworzeniem rzeczywistych obiektów docelowych.
-restoreProperty:{name}={value}

-rp:{name}={value}		 Ustaw lub przesłoń te właściwości na poziomie projektu tylko podczas przywracania i nie używaj właściwości określonych z argumentem -property . name jest nazwą właściwości i value jest wartością właściwości. Użyj średnika lub przecinka, aby oddzielić wiele właściwości lub określić każdą właściwość oddzielnie.
-target:{targets}

-t:{targets}		 Skompiluj określone obiekty docelowe w projekcie. Określ każdy obiekt docelowy oddzielnie lub użyj średnika lub przecinka, aby oddzielić wiele obiektów docelowych, jak pokazano w poniższym przykładzie:

-target:PrepareResources;Compile

Jeśli określisz obiekty docelowe przy użyciu tego przełącznika, zostaną one uruchomione zamiast elementów docelowych w atrybucie DefaultTargets w pliku projektu. Aby uzyskać więcej informacji, zobacz Target build order (Kolejność kompilacji docelowej) i How to: Specify which target to build first (Określanie docelowego celu do skompilowania).

Element docelowy to grupa zadań. Aby uzyskać więcej informacji, zobacz Cele.
-targets[:{file}]

-ts[:{file}]		 Zapisz listę dostępnych obiektów docelowych do określonego pliku (lub urządzenia wyjściowego, jeśli nie określono pliku), bez faktycznego wykonywania procesu kompilacji.
-toolsVersion:{version}

-tv:{version}		 Określa niestandardowy zestaw narzędzi. Zestaw narzędzi składa się z zadań, obiektów docelowych i narzędzi używanych do tworzenia aplikacji. Zobacz Konfiguracje zestawu narzędzi (ToolsVersion) i standardowego i niestandardowego zestawu narzędzi.
-validate:[{schema}]

-val[{schema}]		 Zweryfikuj plik projektu i, jeśli walidacja zakończy się pomyślnie, skompiluj projekt.

Jeśli nie określisz schemawartości , projekt zostanie zweryfikowany względem domyślnego schematu.

Jeśli określisz schemawartość , projekt zostanie zweryfikowany względem określonego schematu.

Oto przykładowe ustawienie: -validate:MyExtendedBuildSchema.xsd
-verbosity:{level}

-v:{level}		 Określa ilość informacji do wyświetlenia w dzienniku kompilacji. Każdy rejestrator wyświetla zdarzenia na podstawie poziomu szczegółowości ustawionego dla tego rejestratora.

Można określić następujące poziomy szczegółowości: q[uiet], , m[inimal]( n[ormal] wartość domyślna), d[etailed]i diag[nostic].

Oto przykładowe ustawienie: -verbosity:quiet
-version

-ver		 Wyświetl tylko informacje o wersji. Projekt nie jest kompilowany.
@{file} Wstaw przełączniki wiersza polecenia z pliku tekstowego. Jeśli masz wiele plików, należy je określić oddzielnie. Aby uzyskać więcej informacji, zobacz Pliki odpowiedzi.
-warnAsError[:{code; ...}]

-err[:{code; ...}]		 Lista kodów ostrzegawczych, które mają być traktowane jako błędy. Użyj średnika lub przecinka, aby oddzielić wiele kodów ostrzegawczych. Aby traktować wszystkie ostrzeżenia jako błędy, użyj przełącznika bez wartości. Gdy ostrzeżenie jest traktowane jako błąd, obiekt docelowy będzie nadal wykonywany tak, jakby był ostrzeżeniem, ale ogólna kompilacja kończy się niepowodzeniem.

Przykład: -err:MSB4130
-warnNotAsError[:{code; ...}]

-noerr[:{code; ...}]		 Program MSBuild 17.0 lub nowszy. Lista kodów ostrzegawczych, które nie powinny być promowane do błędów. W szczególności jeśli przełącznik warnAsError jest ustawiony tak, aby podwyższyć poziom wszystkich ostrzeżeń do błędów, kody błędów określone z ostrzeżeniemNotAsError nie są promowane. Nie ma to wpływu, jeśli właściwość warnAsError nie jest ustawiona na podwyższenie poziomu wszystkich ostrzeżeń do błędów. Użyj średnika lub przecinka, aby oddzielić wiele kodów ostrzegawczych.

Przykład: -noerr:MSB4130
-warnAsMessage[:{code}; ...}]

-noWarn[:{code; ...}]		 Lista kodów ostrzegawczych, które mają być traktowane jako komunikaty o niskiej ważności. Użyj średnika lub przecinka, aby oddzielić wiele kodów ostrzegawczych.

Przykład: -noWarn:MSB3026

Przełączniki dla rejestratorów

Switch opis
-binaryLogger[:[LogFile=]{output.binlog}
[;ProjectImports=None,Embed,ZipFile]]

-bl[:[LogFile=]{output.binlog}
[;ProjectImports=None,Embed,ZipFile]]		 Serializuje wszystkie zdarzenia kompilacji do skompresowanego pliku binarnego. Domyślnie plik znajduje się w bieżącym katalogu o nazwie msbuild.binlog. Dziennik binarny to szczegółowy opis procesu kompilacji, który później może służyć do odtworzenia dzienników tekstowych i używanych przez inne narzędzia do analizy. Dziennik binarny jest zwykle 10-20x mniejszy niż najbardziej szczegółowy dziennik diagnostyczny na poziomie tekstu, ale zawiera więcej informacji.

Rejestrator binarny domyślnie zbiera tekst źródłowy plików projektu, w tym wszystkie zaimportowane projekty i pliki docelowe napotkane podczas kompilacji. Opcjonalny ProjectImports parametr steruje tym zachowaniem:

- ProjectImports=None. Nie zbieraj importów projektu.
- ProjectImports=Embed. Osadzanie importu projektu w pliku dziennika (ustawienie domyślne).
- ProjectImports=ZipFile. Zapisz pliki projektu w lokalizacji {output}.projectimports.zip , gdzie <dane wyjściowe> mają taką samą nazwę jak nazwa pliku dziennika binarnego.

Ustawieniem domyślnym dla opcji ProjectImports jest Osadź.
Uwaga: rejestrator nie zbiera plików źródłowych innych niż MSBuild, takich jak .cs, .cppi tak dalej.
Plik .binlog może być "odtwarzany", przekazując go do msbuild.exe jako argument zamiast projektu/rozwiązania. Inne rejestratory otrzymują informacje zawarte w pliku dziennika tak, jakby oryginalna kompilacja miała miejsce. Więcej informacji na temat dziennika binarnego i jego użycia można uzyskać na stronie: https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md

Przykłady:
- -bl
- -bl:output.binlog
- -bl:output.binlog;ProjectImports=None
- -bl:output.binlog;ProjectImports=ZipFile
- -bl:..\..\custom.binlog
- -binaryLogger
-consoleLoggerParameters:{parameters}

-clp:{parameters}		 Przekaż parametry określone do rejestratora konsoli, który wyświetla informacje o kompilacji w oknie konsoli. Można określić następujące parametry:

- PerformanceSummary. Pokaż czas spędzony w zadaniach, elementach docelowych i projektach.
- Podsumowanie. Pokaż podsumowanie błędu i ostrzeżenia na końcu.
- NoSummary. Na końcu nie pokazuj podsumowania błędów i ostrzeżeń.
- BłędyOnly. Pokaż tylko błędy.
- OstrzeżeniaOnly. Pokaż tylko ostrzeżenia.
- NoItemAndPropertyList. Nie pokazuj listy elementów i właściwości, które będą wyświetlane na początku każdej kompilacji projektu, jeśli poziom szczegółowości jest ustawiony na diagnostic.
- ShowCommandLine. Pokaż TaskCommandLineEvent komunikaty.
- ShowProjectFile. Pokaż ścieżkę do pliku projektu w komunikatach diagnostycznych. To ustawienie jest domyślnie włączone.
- ShowTimestamp. Pokaż znacznik czasu jako prefiks do dowolnego komunikatu.
- ShowEventId. Pokaż identyfikator zdarzenia dla każdego uruchomionego zdarzenia, zakończonego zdarzenia i komunikatu.
- ForceNoAlign. Nie wyrównuj tekstu do rozmiaru buforu konsoli.
- DisableConsoleColor. Użyj domyślnych kolorów konsoli dla wszystkich komunikatów rejestrowania.
- DisableMPLogging. Wyłącz styl rejestrowania wieloprocesorowego danych wyjściowych podczas uruchamiania w trybie nieprocesorowym.
- EnableMPLogging. Włącz styl rejestrowania wieloprocesorowego, nawet jeśli działa w trybie nieprocesorowym. Ten styl rejestrowania jest domyślnie włączony.
- ForceConsoleColor. Użyj kolorów konsoli ANSI, nawet jeśli konsola nie obsługuje jej.
- Szczegółowość. Zastąpi -verbosity ustawienie tego rejestratora.

Użyj średnika, aby oddzielić wiele parametrów, jak pokazano w poniższym przykładzie:

-consoleloggerparameters:PerformanceSummary;NoSummary -verbosity:minimal

Domyślny rejestrator konsoli ma normalną szczegółowość i zawiera element Summary.
-distributedFileLogger

-dfl		 Zarejestruj dane wyjściowe kompilacji każdego węzła MSBuild do własnego pliku. Początkową lokalizacją tych plików jest bieżący katalog. Domyślnie pliki mają nazwę MSBuild{NodeId}.log. Możesz użyć przełącznika -fileLoggerParameters , aby określić lokalizację plików i innych parametrów dla plikuLogger.

Jeśli nazwa pliku dziennika jest używana przy użyciu -fileLoggerParameters przełącznika, rozproszony rejestrator używa tej nazwy jako szablonu i dołącza identyfikator węzła do tej nazwy podczas tworzenia pliku dziennika dla każdego węzła.
-distributedLogger:{central logger},{forwarding logger}, ...

-dl:{central logger},{forwarding logger, ...}		 Rejestruj zdarzenia z programu MSBuild, dołączając inne wystąpienie rejestratora do każdego węzła. Aby określić wiele rejestratorów, określ oddzielnie każdy rejestrator.

Składnia rejestratora służy do określania rejestratora, z wyjątkiem podania i dodatkowej klasy dla rejestratora przekazywania. Aby zapoznać się ze składnią rejestratora -logger , zobacz przełącznik.

W poniższych przykładach pokazano, jak używać tego przełącznika:

-dl:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral

-dl:MyLogger,C:\My.dll*ForwardingLogger,C:\Logger.dll
-fileLogger[{number}]

-fl[{number}]		 Zarejestruj dane wyjściowe kompilacji w jednym pliku w bieżącym katalogu. Jeśli nie określisz numberpliku wyjściowego o nazwie msbuild.log. Jeśli określisz numberwartość , plik wyjściowy nosi nazwę msbuild<n>.log, gdzie <n> to number. Number może być cyfrą z zakresu od 1 do 9.

Możesz użyć przełącznika -fileLoggerParameters , aby określić lokalizację pliku i inne parametry dla plikuLogger.
-fileLoggerParameters[{number}]:

parameters

-flp[{number}]: {parameters}		 Określa wszelkie dodatkowe parametry rejestratora plików i rozproszonego rejestratora plików. Obecność tego przełącznika oznacza, że -filelogger[number] odpowiedni przełącznik jest obecny. Number może być cyfrą z zakresu od 1 do 9.

Możesz użyć wszystkich parametrów wymienionych dla -consoleloggerparameterselementu . Można również użyć jednego lub kilku następujących parametrów:

- LogFile. Ścieżka do pliku dziennika, w którym jest zapisywany dziennik kompilacji. Rozproszony rejestrator plików prefiksuje tę ścieżkę do nazw plików dziennika.
- Dołącz. Określa, czy dziennik kompilacji jest dołączany do pliku dziennika, czy zastępuje go. Po ustawieniu przełącznika dziennik kompilacji jest dołączany do pliku dziennika. Gdy przełącznik nie jest obecny, zawartość istniejącego pliku dziennika zostanie zastąpiona.
Przykład: msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append
Jeśli dołączysz jawne true lub false ustawienie, dziennik zostanie dołączony niezależnie od ustawienia. Jeśli nie dołączysz przełącznika dołączania, dziennik zostanie zastąpiony.
W takim przypadku plik jest zastępowany: msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log
W takim przypadku plik jest dołączany: msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=true
W takim przypadku plik jest dołączany: msbuild myfile.proj -flp:FileLogger,Microsoft.Build;logfile=MyLog.log;append=false
- Kodowanie. Określa kodowanie pliku (na przykład UTF-8, Unicode lub ASCII).

Poniższy przykład generuje oddzielne pliki dziennika dla ostrzeżeń i błędów:

-flp1:logfile=errors.txt;errorsonly -flp2:logfile=warnings.txt;warningsonly

W poniższych przykładach przedstawiono inne możliwości:

-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		 Określa rejestrator, który ma być używany do rejestrowania zdarzeń z programu MSBuild. Aby określić wiele rejestratorów, określ oddzielnie każdy rejestrator.

Użyj następującej składni dla elementu logger: [LoggerClass,]LoggerAssembly[;LoggerParameters]

Użyj następującej składni dla elementu LoggerClass: [PartialOrFullNamespace.]LoggerClassName

Nie musisz określać klasy rejestratora, jeśli zestaw zawiera dokładnie jeden rejestrator.

Użyj następującej składni dla elementu LoggerAssembly: AssemblyName[,StrongName] \| AssemblyFile

Parametry rejestratora są opcjonalne i są przekazywane do rejestratora dokładnie tak, jak zostały wprowadzone.

W poniższych przykładach użyto przełącznika -logger .

-logger:XMLLogger,MyLogger,Version=1.0.2,Culture=neutral

-logger:XMLLogger,C:\Loggers\MyLogger.dll;OutputAsHTML
-noConsoleLogger

-noconlog		 Wyłącz domyślny rejestrator konsoli i nie rejestruj zdarzeń w konsoli programu .
-terminalLogger[:auto,on,off]

-tl[:auto,on,off]		 Włącz lub wyłącz rejestrator terminalu. Rejestrator terminali zapewnia ulepszone dane wyjściowe kompilacji w konsoli w czasie rzeczywistym, uporządkowane logicznie przez projekt i przeznaczone do wyróżniania informacji z możliwością działania. Określ auto (lub użyj opcji bez argumentów), aby użyć rejestratora terminalu tylko wtedy, gdy standardowe dane wyjściowe nie są przekierowywane. Nie analizuj danych wyjściowych ani nie polegaj na tym, że pozostają niezmienione w przyszłych wersjach. Ta opcja jest dostępna w programie MSBuild 17.8 lub nowszym.

Przykład

Poniższy przykład tworzy obiekt docelowy rebuild projektu MyProject.proj .

MSBuild.exe MyProject.proj -t:rebuild

Zobacz też