ASP.NET Core Razor SDK
The .NET 6.0 SDK includes the Microsoft.NET.Sdk.Razor
MSBuild SDK (Razor SDK). The Razor SDK:
- Is required to build, package, and publish projects containing Razor files for ASP.NET Core MVC-based or Blazor projects.
- Includes a set of predefined properties, and items that allow customizing the compilation of Razor (
.cshtml
or.razor
) files.
The Razor SDK includes Content
items with Include
attributes set to the **\*.cshtml
and **\*.razor
globbing patterns. Matching files are published.
Most web apps aren't required to explicitly reference the Razor SDK.
To use the Razor SDK to build class libraries containing Razor views or Razor Pages, we recommend starting with the Razor class library (RCL) project template. An RCL that's used to build Blazor (.razor
) files minimally requires a reference to the Microsoft.AspNetCore.Components package. An RCL that's used to build Razor views or pages (.cshtml
files) minimally requires targeting netcoreapp3.0
or later and has a FrameworkReference
to the Microsoft.AspNetCore.App metapackage in its project file.
The following properties control the Razor's SDK behavior as part of a project build:
RazorCompileOnBuild
: Whentrue
, compiles and emits the Razor assembly as part of building the project. Defaults totrue
.RazorCompileOnPublish
: Whentrue
, compiles and emits the Razor assembly as part of publishing the project. Defaults totrue
.UseRazorSourceGenerator
: Defaults totrue
. Whentrue
:- Compiles using source generation.
- Doesn't create
<app_name>.Views.dll
. Views are included in<app_name>.dll
. - Supports .NET Hot Reload.
The properties and items in the following table are used to configure inputs and output to the Razor SDK.
Items | Description |
---|---|
RazorGenerate |
Item elements (.cshtml files) that are inputs to code generation. |
RazorComponent |
Item elements (.razor files) that are inputs to Razor component code generation. |
RazorCompile |
Item elements (.cs files) that are inputs to Razor compilation targets. Use this ItemGroup to specify additional files to be compiled into the Razor assembly. |
RazorEmbeddedResource |
Item elements added as embedded resources to the generated Razor assembly. |
Property | Description |
---|---|
RazorOutputPath |
The Razor output directory. |
RazorCompileToolset |
Used to determine the toolset used to build the Razor assembly. Valid values are Implicit , RazorSDK , and PrecompilationTool . |
EnableDefaultContentItems | Default is true . When true , includes web.config, .json , and .cshtml files as content in the project. When referenced via Microsoft.NET.Sdk.Web , files under wwwroot and config files are also included. |
EnableDefaultRazorGenerateItems |
When true , includes .cshtml files from Content items in RazorGenerate items. |
GenerateRazorTargetAssemblyInfo |
Not used in .NET 6 and later. |
EnableDefaultRazorTargetAssemblyInfoAttributes |
Not used in .NET 6 and later. |
CopyRazorGenerateFilesToPublishDirectory |
When true , copies RazorGenerate items (.cshtml ) files to the publish directory. Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. Defaults to false . |
PreserveCompilationReferences |
When true , copy reference assembly items to the publish directory. Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. Set to true if your published app requires runtime compilation. For example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. Defaults to false . |
IncludeRazorContentInPack |
When true , all Razor content items (.cshtml files) are marked for inclusion in the generated NuGet package. Defaults to false . |
EmbedRazorGenerateSources |
When true , adds RazorGenerate (.cshtml ) items as embedded files to the generated Razor assembly. Defaults to false . |
GenerateMvcApplicationPartsAssemblyAttributes |
Not used in .NET 6 and later. |
DefaultWebContentItemExcludes |
A globbing pattern for item elements that are to be excluded from the Content item group in projects targeting the Web or Razor SDK |
ExcludeConfigFilesFromBuildOutput |
When true , .config and .json files do not get copied to the build output directory. |
AddRazorSupportForMvc |
When true , configures the Razor SDK to add support for the MVC configuration that is required when building applications containing MVC views or Razor Pages. This property is implicitly set for .NET Core 3.0 or later projects targeting the Web SDK |
RazorLangVersion |
The version of the Razor Language to target. |
EmitCompilerGeneratedFiles |
When set to true , the generated source files are written to disk. Setting to true is useful when debugging the compiler. The default is false . |
For more information on properties, see MSBuild properties.
By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime compilation. This results in compilation failures when the application model relies on runtime compilation—for example, the app uses embedded views or changes views after the app is published. Set
CopyRefAssembliesToPublishDirectory
totrue
to continue publishing reference assemblies. Both code generation and compilation are supported by a single call to the compiler. A single assembly is produced that contains the app types and the generated views.For a web app, ensure your app is targeting the
Microsoft.NET.Sdk.Web
SDK.
When targeting the Microsoft.NET.Sdk.Web
SDK, the Razor language version is inferred from the app's target framework version. For projects targeting the Microsoft.NET.Sdk.Razor
SDK or in the rare case that the app requires a different Razor language version than the inferred value, a version can be configured by setting the <RazorLangVersion>
property in the app's project file:
<PropertyGroup>
<RazorLangVersion>{VERSION}</RazorLangVersion>
</PropertyGroup>
Razor's language version is tightly integrated with the version of the runtime that it was built for. Targeting a language version that isn't designed for the runtime is unsupported and likely produces build errors.
The .NET Core 2.1 SDK or later includes the Microsoft.NET.Sdk.Razor
MSBuild SDK (Razor SDK). The Razor SDK:
- Is required to build, package, and publish projects containing Razor files for ASP.NET Core MVC-based or Blazor projects.
- Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor (
.cshtml
or.razor
) files.
The Razor SDK includes Content
items with Include
attributes set to the **\*.cshtml
and **\*.razor
globbing patterns. Matching files are published.
Most web apps aren't required to explicitly reference the Razor SDK.
To use the Razor SDK to build class libraries containing Razor views or Razor Pages, we recommend starting with the Razor class library (RCL) project template. An RCL that's used to build Blazor (.razor
) files minimally requires a reference to the Microsoft.AspNetCore.Components package. An RCL that's used to build Razor views or pages (.cshtml
files) minimally requires targeting netcoreapp3.0
or later and has a FrameworkReference
to the Microsoft.AspNetCore.App metapackage in its project file.
The following properties control the Razor's SDK behavior as part of a project build:
RazorCompileOnBuild
: Whentrue
, compiles and emits the Razor assembly as part of building the project. Defaults totrue
.RazorCompileOnPublish
: Whentrue
, compiles and emits the Razor assembly as part of publishing the project. Defaults totrue
.
The properties and items in the following table are used to configure inputs and output to the Razor SDK.
Warning
Starting with ASP.NET Core 3.0, MVC Views or Razor Pages aren't served by default if the RazorCompileOnBuild
or RazorCompileOnPublish
MSBuild properties in the project file are disabled. Applications must add an explicit reference to the Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation package if the app relies on runtime compilation to process .cshtml
files.
Items | Description |
---|---|
RazorGenerate |
Item elements (.cshtml files) that are inputs to code generation. |
RazorComponent |
Item elements (.razor files) that are inputs to Razor component code generation. |
RazorCompile |
Item elements (.cs files) that are inputs to Razor compilation targets. Use this ItemGroup to specify additional files to be compiled into the Razor assembly. |
RazorTargetAssemblyAttribute |
Item elements used to code generate attributes for the Razor assembly. For example: RazorAssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute" _Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/"> |
RazorEmbeddedResource |
Item elements added as embedded resources to the generated Razor assembly. |
Property | Description |
---|---|
RazorTargetName |
File name (without extension) of the assembly produced by Razor. |
RazorOutputPath |
The Razor output directory. |
RazorCompileToolset |
Used to determine the toolset used to build the Razor assembly. Valid values are Implicit , RazorSDK , and PrecompilationTool . |
EnableDefaultContentItems | Default is true . When true , includes web.config, .json , and .cshtml files as content in the project. When referenced via Microsoft.NET.Sdk.Web , files under wwwroot and config files are also included. |
EnableDefaultRazorGenerateItems |
When true , includes .cshtml files from Content items in RazorGenerate items. |
GenerateRazorTargetAssemblyInfo |
When true , generates a .cs file containing attributes specified by RazorAssemblyAttribute and includes the file in the compile output. |
EnableDefaultRazorTargetAssemblyInfoAttributes |
When true , adds a default set of assembly attributes to RazorAssemblyAttribute . |
CopyRazorGenerateFilesToPublishDirectory |
When true , copies RazorGenerate items (.cshtml ) files to the publish directory. Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. Defaults to false . |
PreserveCompilationReferences |
When true , copy reference assembly items to the publish directory. Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. Set to true if your published app requires runtime compilation. For example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. Defaults to false . |
IncludeRazorContentInPack |
When true , all Razor content items (.cshtml files) are marked for inclusion in the generated NuGet package. Defaults to false . |
EmbedRazorGenerateSources |
When true , adds RazorGenerate (.cshtml ) items as embedded files to the generated Razor assembly. Defaults to false . |
UseRazorBuildServer |
When true , uses a persistent build server process to offload code generation work. Defaults to the value of UseSharedCompilation . |
GenerateMvcApplicationPartsAssemblyAttributes |
When true , the SDK generates additional attributes used by MVC at runtime to perform application part discovery. |
DefaultWebContentItemExcludes |
A globbing pattern for item elements that are to be excluded from the Content item group in projects targeting the Web or Razor SDK |
ExcludeConfigFilesFromBuildOutput |
When true , .config and .json files do not get copied to the build output directory. |
AddRazorSupportForMvc |
When true , configures the Razor SDK to add support for the MVC configuration that is required when building applications containing MVC views or Razor Pages. This property is implicitly set for .NET Core 3.0 or later projects targeting the Web SDK |
RazorLangVersion |
The version of the Razor Language to target. |
For more information on properties, see MSBuild properties.
The Razor SDK defines two primary targets:
RazorGenerate
: Code generates.cs
files fromRazorGenerate
item elements. Use theRazorGenerateDependsOn
property to specify additional targets that can run before or after this target.RazorCompile
: Compiles generated.cs
files in to a Razor assembly. Use theRazorCompileDependsOn
to specify additional targets that can run before or after this target.RazorComponentGenerate
: Code generates.cs
files forRazorComponent
item elements. Use theRazorComponentGenerateDependsOn
property to specify additional targets that can run before or after this target.
By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime compilation. This results in compilation failures when the application model relies on runtime compilation—for example, the app uses embedded views or changes views after the app is published. Set
CopyRefAssembliesToPublishDirectory
totrue
to continue publishing reference assemblies.For a web app, ensure your app is targeting the
Microsoft.NET.Sdk.Web
SDK.
When targeting the Microsoft.NET.Sdk.Web
SDK, the Razor language version is inferred from the app's target framework version. For projects targeting the Microsoft.NET.Sdk.Razor
SDK or in the rare case that the app requires a different Razor language version than the inferred value, a version can be configured by setting the <RazorLangVersion>
property in the app's project file:
<PropertyGroup>
<RazorLangVersion>{VERSION}</RazorLangVersion>
</PropertyGroup>
Razor's language version is tightly integrated with the version of the runtime that it was built for. Targeting a language version that isn't designed for the runtime is unsupported and likely produces build errors.
- Standardizes the experience around building, packaging, and publishing projects containing Razor files for ASP.NET Core MVC-based projects.
- Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor files.
The Razor SDK includes a Content
item with an Include
attribute set to the **\*.cshtml
globbing pattern. Matching files are published.
Most web apps aren't required to explicitly reference the Razor SDK.
To use the Razor SDK to build class libraries containing Razor views or Razor Pages:
Use
Microsoft.NET.Sdk.Razor
instead ofMicrosoft.NET.Sdk
:<Project SDK="Microsoft.NET.Sdk.Razor"> <!-- omitted for brevity --> </Project>
Typically, a package reference to
Microsoft.AspNetCore.Mvc
is required to receive additional dependencies that are required to build and compile Razor Pages and Razor views. At a minimum, your project should add package references to:Microsoft.AspNetCore.Razor.Design
Microsoft.AspNetCore.Mvc.Razor.Extensions
Microsoft.AspNetCore.Mvc.Razor
The
Microsoft.AspNetCore.Razor.Design
package provides the Razor compilation tasks and targets for the project.The preceding packages are included in
Microsoft.AspNetCore.Mvc
. The following markup shows a project file that uses the Razor SDK to build Razor files for an ASP.NET Core Razor Pages app:<Project Sdk="Microsoft.NET.Sdk.Razor"> <PropertyGroup> <TargetFramework>netcoreapp2.1</TargetFramework> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.3" /> </ItemGroup> </Project>
Warning
The Microsoft.AspNetCore.Razor.Design
and Microsoft.AspNetCore.Mvc.Razor.Extensions
packages are included in the Microsoft.AspNetCore.App metapackage. However, the version-less Microsoft.AspNetCore.App
package reference provides a metapackage to the app that doesn't include the latest version of Microsoft.AspNetCore.Razor.Design
. Projects must reference a consistent version of Microsoft.AspNetCore.Razor.Design
(or Microsoft.AspNetCore.Mvc
) so that the latest build-time fixes for Razor are included. For more information, see this GitHub issue.
The following properties control the Razor's SDK behavior as part of a project build:
RazorCompileOnBuild
: Whentrue
, compiles and emits the Razor assembly as part of building the project. Defaults totrue
.RazorCompileOnPublish
: Whentrue
, compiles and emits the Razor assembly as part of publishing the project. Defaults totrue
.
The properties and items in the following table are used to configure inputs and output to the Razor SDK.
Items | Description |
---|---|
RazorGenerate |
Item elements (.cshtml files) that are inputs to code generation. |
RazorComponent |
Item elements (.razor files) that are inputs to Razor component code generation. |
RazorCompile |
Item elements (.cs files) that are inputs to Razor compilation targets. Use this ItemGroup to specify additional files to be compiled into the Razor assembly. |
RazorTargetAssemblyAttribute |
Item elements used to code generate attributes for the Razor assembly. For example: RazorAssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute" _Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/"> |
RazorEmbeddedResource |
Item elements added as embedded resources to the generated Razor assembly. |
Property | Description |
---|---|
RazorTargetName |
File name (without extension) of the assembly produced by Razor. |
RazorOutputPath |
The Razor output directory. |
RazorCompileToolset |
Used to determine the toolset used to build the Razor assembly. Valid values are Implicit , RazorSDK , and PrecompilationTool . |
EnableDefaultContentItems | Default is true . When true , includes web.config, .json , and .cshtml files as content in the project. When referenced via Microsoft.NET.Sdk.Web , files under wwwroot and config files are also included. |
EnableDefaultRazorGenerateItems |
When true , includes .cshtml files from Content items in RazorGenerate items. |
GenerateRazorTargetAssemblyInfo |
When true , generates a .cs file containing attributes specified by RazorAssemblyAttribute and includes the file in the compile output. |
EnableDefaultRazorTargetAssemblyInfoAttributes |
When true , adds a default set of assembly attributes to RazorAssemblyAttribute . |
CopyRazorGenerateFilesToPublishDirectory |
When true , copies RazorGenerate items (.cshtml ) files to the publish directory. Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. Defaults to false . |
CopyRefAssembliesToPublishDirectory |
When true , copy reference assembly items to the publish directory. Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. Set to true if your published app requires runtime compilation. For example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. Defaults to false . |
IncludeRazorContentInPack |
When true , all Razor content items (.cshtml files) are marked for inclusion in the generated NuGet package. Defaults to false . |
EmbedRazorGenerateSources |
When true , adds RazorGenerate (.cshtml ) items as embedded files to the generated Razor assembly. Defaults to false . |
UseRazorBuildServer |
When true , uses a persistent build server process to offload code generation work. Defaults to the value of UseSharedCompilation . |
GenerateMvcApplicationPartsAssemblyAttributes |
When true , the SDK generates additional attributes used by MVC at runtime to perform application part discovery. |
DefaultWebContentItemExcludes |
A globbing pattern for item elements that are to be excluded from the Content item group in projects targeting the Web or Razor SDK |
ExcludeConfigFilesFromBuildOutput |
When true , .config and .json files do not get copied to the build output directory. |
AddRazorSupportForMvc |
When true , configures the Razor SDK to add support for the MVC configuration that is required when building applications containing MVC views or Razor Pages. This property is implicitly set for .NET Core 3.0 or later projects targeting the Web SDK |
RazorLangVersion |
The version of the Razor Language to target. |
For more information on properties, see MSBuild properties.
The Razor SDK defines two primary targets:
RazorGenerate
: Code generates.cs
files fromRazorGenerate
item elements. Use theRazorGenerateDependsOn
property to specify additional targets that can run before or after this target.RazorCompile
: Compiles generated.cs
files in to a Razor assembly. Use theRazorCompileDependsOn
to specify additional targets that can run before or after this target.RazorComponentGenerate
: Code generates.cs
files forRazorComponent
item elements. Use theRazorComponentGenerateDependsOn
property to specify additional targets that can run before or after this target.
By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime compilation. This results in compilation failures when the application model relies on runtime compilation—for example, the app uses embedded views or changes views after the app is published. Set
CopyRefAssembliesToPublishDirectory
totrue
to continue publishing reference assemblies.For a web app, ensure your app is targeting the
Microsoft.NET.Sdk.Web
SDK.
When targeting the Microsoft.NET.Sdk.Web
SDK, the Razor language version is inferred from the app's target framework version. For projects targeting the Microsoft.NET.Sdk.Razor
SDK or in the rare case that the app requires a different Razor language version than the inferred value, a version can be configured by setting the <RazorLangVersion>
property in the app's project file:
<PropertyGroup>
<RazorLangVersion>{VERSION}</RazorLangVersion>
</PropertyGroup>
Razor's language version is tightly integrated with the version of the runtime that it was built for. Targeting a language version that isn't designed for the runtime is unsupported and likely produces build errors.
ASP.NET Core feedback
ASP.NET Core is an open source project. Select a link to provide feedback: