Dokumentacja wiersza polecenia programu MSBuild

W przypadku użycia MSBuild.exe do utworzenia pliku projektu lub rozwiązania można dołączyć kilka przełączników w celu określenia różnych aspektów procesu.

Każdy przełącznik jest dostępny w dwóch formach: -switch i /switch. W dokumentacji przedstawiono tylko formularz -switch. Przełączniki nie są uwzględniane wielkości liter. Jeśli uruchomisz MSBuild z powłoki innej niż wiersz polecenia 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 MSBuild zamiast interpretowane przez powłokę.

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, MSBuild przeszukuje bieżący katalog roboczy dla rozszerzenia nazwy pliku, które kończy się na proj i używa tego pliku. Możesz również określić plik rozwiązania Visual Studio dla tego argumentu.

Przełączniki

Przełącznik Forma krótka Opis
-detailedSummary -ds Pokaż 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.
-graphBuild[:True lub False] -graph[:True lub False] Powoduje, że MSBuild konstruować i kompilować graf projektu. Konstruowanie grafu obejmuje identyfikowanie odwołań projektu do zależności formularzy. Tworzenie tego grafu obejmuje próbę skompilowania odwołań do projektu przed projektami odwołującymi się do nich, różniąc się od tradycyjnego planowania MSBuild. Wymaga MSBuild 16 lub nowszych.
— Pomoc /? lub -h Wyświetl informacje o użyciu. Następujące polecenie jest przykładem:

msbuild.exe -?
-ignoreProjectExtensions: extensions -ignoruj: 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
-interactive[:True lub False] - Wskazuje, że akcje w kompilacji mogą współdziałać z użytkownikiem. Nie używaj tego argumentu w zautomatyzowanym scenariuszu, w którym nie oczekuje się interakcyjności. Określanie parametru -interactive jest takie samo jak określenie -interactive:true. Użyj parametru , aby zastąpić wartość pochodzącą z pliku odpowiedzi.
-isolateProjects[:True lub False] -isolate[:True lub False] Powoduje, że MSBuild skompilować każdy projekt w izolacji. Jest to bardziej restrykcyjny tryb MSBuild, 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.
-maxCpuCount[:number] -m[:number] Określa maksymalną liczbę współbieżnych procesów do użycia podczas kompilowania. Jeśli nie dołączysz tego przełącznika, wartość domyślna to 1. Jeśli ten przełącznik zostanie uwzględniny bez określenia wartości, MSBuild będzie używać maksymalnie liczby procesorów na komputerze. Aby uzyskać więcej informacji, zobacz Kompilowanie wielu projektów równolegle.

W poniższym przykładzie przedstawiono instrukcje MSBuild kompilowania przy użyciu trzech procesów MSBuild, co umożliwia jednoczesne kompilowanie trzech projektów:

msbuild myproject.proj -maxcpucount:3
-noAutoResponse -noautorsp Nie dołączaj automatycznie żadnych plików MSBuild.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 dołączysz przełącznik -maxcpucount , wiele węzłów może być wykonywanych współbieżnie.
-nologo Nie wyświetlaj baneru startowego ani komunikatu 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, z lokalizacji, z której 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 element filepath, zagregowany plik projektu jest wyjściowy do pliku. W przeciwnym razie dane wyjściowe są wyświetlane w oknie konsoli.

Aby uzyskać informacje o sposobie stosowania Import elementu do wstawiania pliku projektu do innego pliku projektu, zobacz Importowanie elementu (MSBuild) i Instrukcje: używanie tego samego elementu docelowego w wielu plikach projektu.
-outputResultsCache[:cacheFile] -orc[:cacheFile] Wyjściowy plik pamięci podręcznej, w którym MSBuild zapisze zawartość pamięci podręcznej wyników kompilacji na końcu kompilacji. Ustawienie powoduje również włączenie izolowanych kompilacji (izolowanie).
-profileEvaluation:<file> - Profile MSBuild oceny i zapisują wynik do określonego pliku. Jeśli rozszerzenie określonego pliku to ".md", wynik jest generowany w formacie Markdown. W przeciwnym razie generowany jest 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
-Przywracanie -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 poszczególne obiekty docelowe 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 jakiekolwiek obiekty docelowe przy użyciu tego przełącznika, zostaną one uruchomione zamiast wszystkich obiektó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 kompilacji).

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 wykonania procesu kompilacji.
-toolsVersion:version -tv:version Określa wersję zestawu narzędzi do skompilowania projektu, jak pokazano w poniższym przykładzie: -toolsversion:3.5

Korzystając z tego przełącznika, można utworzyć projekt i określić wersję, która różni się od wersji określonej w elemecie Project (MSBuild). Aby uzyskać więcej informacji, zobacz Zastępowanie ustawień ToolsVersion.

W przypadku MSBuild 4.5 można określić następujące wartości: version2.0, 3.5 i 4.0. Jeśli określisz 4.0, VisualStudioVersion właściwość kompilacji określa zestaw narzędzi podrzędnych do użycia. Aby uzyskać więcej informacji, zobacz sekcję Zestawy narzędzi podrzędnych zestawu narzędzi (ToolsVersion).

Zestaw narzędzi składa się z zadań, elementów docelowych i narzędzi używanych do tworzenia aplikacji. Narzędzia obejmują kompilatory, takie jak csc.exe i vbc.exe. Aby uzyskać więcej informacji na temat zestawów narzędzi, zobacz Zestaw narzędzi (ToolsVersion), Konfiguracje zestawów narzędzi standardowych i niestandardowych oraz Wielotargeting. Uwaga: Wersja zestawu narzędzi nie jest taka sama jak struktura docelowa, która jest wersją .NET Framework, na której jest tworzony projekt. Aby uzyskać więcej informacji, zobacz Platforma docelowa i platforma docelowa.
-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] (domyślne), d[etailed]i diag[nostic].

Oto przykładowe ustawienie: -verbosity:quiet
-Wersja -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[;code2] -err[:code[;code2] Lista kodów ostrzegawczych do traktowania jako błędów. 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, docelowy będzie nadal wykonywany tak, jakby był to ostrzeżenie, ale ogólna kompilacja kończy się niepowodzeniem.

Przykład: -err:MSB4130
-warnNotAsError[:code[;code2] -noerr[:code``;code2] 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 na podwyższenie poziomu wszystkich ostrzeżeń do błędów, kody błędów określone za pomocą funkcji warnNotAsError nie są promowane. Nie ma to wpływu, jeśli właściwość warnAsError nie jest ustawiona w celu podwyższenia 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[;code2] -noWarn[:code[;code2] Lista kodów ostrzegawczych do traktowania jako komunikatów 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

Przełącznik Forma krótka Opis
-binaryLogger[:[LogFile=]output.binlog
[; ProjectImports=[None,Embed,ZipFile]]]
-bl 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 może później służyć do odtworzenia dzienników tekstowych i używanych przez inne narzędzia do analizy. Dziennik binarny jest zwykle 10-20 x 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 przełącznik steruje tym zachowaniem:

- ProjectImports=None. Nie zbieraj importu projektu.
- ProjectImports=Embed. Osadzanie importu projektu w pliku dziennika (wartość domyślna).
- ProjectImports=ZipFile. Zapisz pliki projektu w <output>pliku .projectimports.zip , gdzie <output> jest taka sama 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, cpp itp.
Plik .binlog można "odtworzyć", przekazując go do msbuild.exe jako argument zamiast projektu/rozwiązania. Inne rejestratory otrzymają 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ć pod adresem: 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. Nie pokazuj podsumowania błędu i ostrzeżenia na końcu.
- 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 pojawią się na początku każdej kompilacji projektu, jeśli poziom szczegółowości ma wartość diagnostic.
- ShowCommandLine. Pokaż TaskCommandLineEvent komunikaty.
- ShowTimestamp. Pokaż znacznik czasu jako prefiks dowolnej wiadomości.
- ShowEventId. Pokaż identyfikator zdarzenia dla każdego rozpoczętego 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 w przypadku uruchamiania w trybie nieprocesorowym. Ten styl rejestrowania jest domyślnie włączony.
- Szczegółowość. Zastąpij ustawienie -verbosity dla 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.log<NodeId>. Możesz użyć przełącznika -fileLoggerParameters , aby określić lokalizację plików i innych parametrów dla plikuLogger.

Jeśli nadasz plikowi dziennika nazwę przy użyciu przełącznika -fileLoggerParameters , rozproszony rejestrator użyje tej nazwy jako szablonu i dołącz 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 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. Aby uzyskać informacje o składni rejestratora, zobacz przełącznik -logger poniżej.

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

[liczba]
-fl[number] Zarejestruj dane wyjściowe kompilacji w pojedynczym 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 ma nazwę msbuild.log<n>, 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 odpowiedni przełącznik -filelogger[number] jest obecny. Number może być cyfrą z zakresu od 1 do 9.

Możesz użyć wszystkich parametrów wymienionych dla parametrów -consoleloggerparameters. Można również użyć co najmniej jednego z 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 jest zastępowana.
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 zostanie zastąpiony: 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
-rejestrator:

logger
-l:logger Określa rejestrator, który ma być używany do rejestrowania zdarzeń z 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``] &#124; AssemblyFile``}

Parametry rejestratora są opcjonalne i są przekazywane do rejestratora dokładnie tak, jak je wprowadzasz.

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 .

Przykład 1

Poniższy przykład kompiluje rebuild cel projektu MyProject.proj .

MSBuild.exe MyProject.proj -t:rebuild

Przykład 2

Możesz użyć MSBuild.exe do wykonywania bardziej złożonych kompilacji. Można na przykład użyć go do tworzenia określonych obiektów docelowych określonych projektów w rozwiązaniu. Poniższy przykład ponownie kompiluje projekt NotInSolutionFolder i czyści projekt InSolutionFolder, który znajduje się w folderze Rozwiązania NewFolder .

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

Zobacz też