1dotnet-build(1) .NET Documentation dotnet-build(1)
2
6 This article applies to: ✔️ .NET Core 3.1 SDK and later versions
7
9 dotnet-build - Builds a project and all of its dependencies.
10
12 dotnet build [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
13 [-c|--configuration <CONFIGURATION>] [-f|--framework <FRAMEWORK>]
14 [--force] [--interactive] [--no-dependencies] [--no-incremental]
15 [--no-restore] [--nologo] [--no-self-contained] [--os <OS>]
16 [-o|--output <OUTPUT_DIRECTORY>] [-r|--runtime <RUNTIME_IDENTIFIER>]
17 [--self-contained [true|false]] [--source <SOURCE>] [--use-current-runtime, --ucr [true|false]]
18 [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]
19 dotnet build -h|--help
21
23 The dotnet build command builds the project and its dependencies into a
24 set of binaries. The binaries include the project’s code in Intermedi‐
25 ate Language (IL) files with a .dll extension. Depending on the
26 project type and settings, other files may be included, such as:
27 • An executable that can be used to run the application, if the project
29 type is an executable targeting .NET Core 3.0 or later.
30 • Symbol files used for debugging with a .pdb extension.
32 • A .deps.json file, which lists the dependencies of the application or
34 library.
35 • A .runtimeconfig.json file, which specifies the shared runtime and
37 its version for an application.
38 • Other libraries that the project depends on (via project references
40 or NuGet package references).
41 For executable projects targeting versions earlier than .NET Core 3.0,
43 library dependencies from NuGet are typically NOT copied to the output
44 folder. They’re resolved from the NuGet global packages folder at run
45 time. With that in mind, the product of dotnet build isn’t ready to be
46 transferred to another machine to run. To create a version of the ap‐
47 plication that can be deployed, you need to publish it (for example,
48 with the dotnet publish command). For more information, see .NET Ap‐
49 plication Deployment.
50 For executable projects targeting .NET Core 3.0 and later, library de‐
52 pendencies are copied to the output folder. This means that if there
53 isn’t any other publish-specific logic (such as Web projects have), the
54 build output should be deployable.
55 Implicit restore
57 Building requires the project.assets.json file, which lists the depen‐
58 dencies of your application. The file is created when dotnet restore
59 is executed. Without the assets file in place, the tooling can’t re‐
60 solve reference assemblies, which results in errors.
61 You don’t have to run dotnet restore because it’s run implicitly by all
63 commands that require a restore to occur, such as dotnet new, dotnet
64 build, dotnet run, dotnet test, dotnet publish, and dotnet pack. To
65 disable implicit restore, use the --no-restore option.
66 The dotnet restore command is still useful in certain scenarios where
68 explicitly restoring makes sense, such as continuous integration builds
69 in Azure DevOps Services or in build systems that need to explicitly
70 control when the restore occurs.
71 For information about how to manage NuGet feeds, see the dotnet restore
73 documentation.
74 This command supports the dotnet restore options when passed in the
76 long form (for example, --source). Short form options, such as -s, are
77 not supported.
78 Executable or library output
80 Whether the project is executable or not is determined by the <Output‐
81 Type> property in the project file. The following example shows a
82 project that produces executable code:
83 <PropertyGroup>
85 <OutputType>Exe</OutputType>
86 </PropertyGroup>
87 To produce a library, omit the <OutputType> property or change its val‐
89 ue to Library. The IL DLL for a library doesn’t contain entry points
90 and can’t be executed.
91 MSBuild
93 dotnet build uses MSBuild to build the project, so it supports both
94 parallel and incremental builds. For more information, see Incremental
95 Builds.
96 In addition to its options, the dotnet build command accepts MSBuild
98 options, such as -p for setting properties or -l to define a logger.
99 For more information about these options, see the MSBuild Command-Line
100 Reference. Or you can also use the dotnet msbuild command.
101 When dotnet build is run automatically by dotnet run, arguments
103 like -property:property=value aren’t respected.
104 Running dotnet build is equivalent to running dotnet msbuild -restore;
106 however, the default verbosity of the output is different.
107 Workload manifest downloads
109 When you run this command, it initiates an asynchronous background
110 download of advertising manifests for workloads. If the download is
111 still running when this command finishes, the download is stopped. For
112 more information, see Advertising manifests.
113
115 PROJECT | SOLUTION
116 The project or solution file to build. If a project or solution file
118 isn’t specified, MSBuild searches the current working directory for a
119 file that has a file extension that ends in either proj or sln and uses
120 that file.
121
123 • -a|--arch <ARCHITECTURE>
124 Specifies the target architecture. This is a shorthand syntax for
126 setting the Runtime Identifier (RID), where the provided value is
127 combined with the default RID. For example, on a win-x64 machine,
128 specifying --arch x86 sets the RID to win-x86. If you use this op‐
129 tion, don’t use the -r|--runtime option. Available since .NET 6 Pre‐
130 view 7.
131 • -c|--configuration <CONFIGURATION>
133 Defines the build configuration. The default for most projects is
135 Debug, but you can override the build configuration settings in your
136 project.
137 • -f|--framework <FRAMEWORK>
139 Compiles for a specific framework. The framework must be defined in
141 the project file. Examples: net7.0, net462.
142 • --force
144 Forces all dependencies to be resolved even if the last restore was
146 successful. Specifying this flag is the same as deleting the
147 project.assets.json file.
148 • -?|-h|--help
150 Prints out a description of how to use the command.
152 • --interactive
154 Allows the command to stop and wait for user input or action. For
156 example, to complete authentication. Available since .NET Core 3.0
157 SDK.
158 • --no-dependencies
160 Ignores project-to-project (P2P) references and only builds the spec‐
162 ified root project.
163 • --no-incremental
165 Marks the build as unsafe for incremental build. This flag turns off
167 incremental compilation and forces a clean rebuild of the project’s
168 dependency graph.
169 • --no-restore
171 Doesn’t execute an implicit restore during build.
173 • --nologo
175 Doesn’t display the startup banner or the copyright message.
177 • --no-self-contained
179 Publishes the application as a framework dependent application. A
181 compatible .NET runtime must be installed on the target machine to
182 run the application. Available since .NET 6 SDK.
183 • -o|--output <OUTPUT_DIRECTORY>
185 Directory in which to place the built binaries. If not specified,
187 the default path is ./bin/<configuration>/<framework>/. For projects
188 with multiple target frameworks (via the TargetFrameworks property),
189 you also need to define --framework when you specify this option.
190 • --os <OS>
192 Specifies the target operating system (OS). This is a shorthand syn‐
194 tax for setting the Runtime Identifier (RID), where the provided val‐
195 ue is combined with the default RID. For example, on a win-x64 ma‐
196 chine, specifying --os linux sets the RID to linux-x64. If you use
197 this option, don’t use the -r|--runtime option. Available since .NET
198 6.
199 • -r|--runtime <RUNTIME_IDENTIFIER>
201 Specifies the target runtime. For a list of Runtime Identifiers
203 (RIDs), see the RID catalog. If you use this option with .NET 6 SDK,
204 use --self-contained or --no-self-contained also. If not specified,
205 the default is to build for the current OS and architecture.
206 • --self-contained [true|false]
208 Publishes the .NET runtime with the application so the runtime
210 doesn’t need to be installed on the target machine. The default is
211 true if a runtime identifier is specified. Available since .NET 6
212 SDK.
213 • --source <SOURCE>
215 The URI of the NuGet package source to use during the restore opera‐
217 tion.
218 • -v|--verbosity <LEVEL>
220 Sets the verbosity level of the command. Allowed values are q[uiet],
222 m[inimal], n[ormal], d[etailed], and diag[nostic]. The default is
223 minimal. For more information, see <xref:Microsoft.Build.Frame‐
224 work.LoggerVerbosity>.
225 • --use-current-runtime, --ucr [true|false]
227 Sets the RuntimeIdentifier to a platform portable RuntimeIdentifier
229 based on the one of your machine. This happens implicitly with prop‐
230 erties that require a RuntimeIdentifier, such as SelfContained, Pub‐
231 lishAot, PublishSelfContained, PublishSingleFile, and PublishReady‐
232 ToRun. If the property is set to false, that implicit resolution
233 will no longer occur.
234 • --version-suffix <VERSION_SUFFIX>
236 Sets the value of the $(VersionSuffix) property to use when building
238 the project. This only works if the $(Version) property isn’t set.
239 Then, $(Version) is set to the $(VersionPrefix) combined with the
240 $(VersionSuffix), separated by a dash.
241
243 • Build a project and its dependencies:
244 dotnet build
246 • Build a project and its dependencies using Release configuration:
248 dotnet build --configuration Release
250 • Build a project and its dependencies for a specific runtime (in this
252 example, Ubuntu 18.04):
253 dotnet build --runtime ubuntu.18.04-x64
255 • Build the project and use the specified NuGet package source during
257 the restore operation:
258 dotnet build --source c:\packages\mypackages
260 • Build the project and set version 1.2.3.4 as a build parameter using
262 the -p MSBuild option:
263 dotnet build -p:Version=1.2.3.4
265 2022-10-21 dotnet-build(1)