Razor Class Libraries are .NET class libraries setup with the Razor SDK to enable building Razor files (.razor, cshtml) and to include client web assets (.js, .css, images, etc.). Client web assets often need to be built or processed using tools like npm and webpack. But integrating a client web asset build pipeline into the build process of a Razor Class Library can be challenging. It’s error prone and sometimes results in fragile solutions, like relying on the ordering of tasks in the build process that can change between releases.<\/p>\n
In this post we’ll show you how to integrate npm and webpack into the build process for your Razor Class Library. For folks who want a solution that just works, we’ll look at the new experimental Microsoft.AspNetCore.ClientAssets<\/a> package that handles this integration for you automatically provided you have the right tools installed. We’ll also walk through all the details of how to set this up using MSBuild for folks that want to be able to control and customize the process. While the focus of this post is npm and webpack, the solution that we provide here can easily be adapted to other tools like yarn, rollup, etc.<\/p>\n There are two things that we want to happen as part of the build process to integrate handling of client web assets:<\/p>\n In our examples, we’ll put all the client web asset sources into an assets<\/em> folder within the root of the project.<\/p>\n For the output of the build process we have a couple of options:<\/p>\n Ideally, we want these steps to be incremental, meaning that they only run when any of the inputs have changed and don’t run when everything is up to date. For example, we only want to run All of this build logic can be included in a NuGet package and reused across multiple projects. In fact, that’s what we’ve done in the experimental Microsoft.AspNetCore.ClientAssets<\/a> package, which will automatically add support for integrating npm, webpack, or other tools to your build pipeline.<\/p>\n To use the MicrosoftAspNetCore.ClientAssets package:<\/p>\n That’s it! You’re ready to restore and build your client web assets. You can find a sample that shows using this package to build TypeScript files in a Razor Class Library here<\/a>.<\/p>\n We think this package will fit the needs of most users, but give it a try and let us know what you think by submitting any issues you find on GitHub<\/a>. If for some reason this doesn’t work for a tool you’re using, you can add the MSBuild logic directly to your project and update and adapt it to fit your needs. We’ll cover that next.<\/p>\n The MicrosoftAspNetCore.ClientAssets package provides custom MSBuild targets to add a client web assets build process to your project. In this section, we’ll look at how these targets work, so that you can customize them.<\/p>\n To restore client web assets from npm, we’ll create a task to invoke The complete target is displayed below:<\/p>\n Next we’ll create a target that runs an npm command and collects the outputs as static web assets. In our example, we’ll create an The We’ll start by defining the Next we’ll add the build outputs as The The last step is to make this target run only when the sources are changed. To do so, we need to declare Given that we don’t know what the outputs of running the npm command are going to be, we’ll generate a file with the list of output files. The output file listing will always have a well-known file name (npmbuild.complete.txt<\/em>), so we’ll be able to use it as the output for our target. We can produce the output file listing like this:<\/p>\n Since we’re generating a file, we also need to add it to the list of For the inputs, we can define an item group to capture them as follows:<\/p>\n With all that in place, we can define the inputs and outputs on our This target will only run when you change something in your sources, like your TypeScript files or package.json<\/em>.<\/p>\n With these targets the build pipeline will invoke The parameters passed from the We’ve seen in detail how to put together all the pieces. However, we’ve been very strict in what command to run, where the files should be located, and so on. Next we’ll generalize the solution by using MSBuild to parameterize the process. Here’s how:<\/p>\n With the changes we made above, we can adapt the build process by changing the values for the different properties in our project file. For example, we can specify that our client web assets are in the js<\/em> folder instead of the assets<\/em>, or change the list of default exclusions:<\/p>\n Adding a client web assets build process to your .NET projects is now easy using the new experimental Microsoft.AspNetCore.ClientAssets<\/a> package. Or you can create a custom build process using similar MSBuild logic to fit your needs. We hope you’ll give this functionality a try and let us know what you think on GitHub<\/a>.<\/p>\n Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":" Learn how to integrate a build process for client web assets using tools like npm and webpack into the builds of your Razor Class Libraries.<\/p>\n","protected":false},"author":1866,"featured_media":37184,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685,197,7509],"tags":[],"class_list":["post-37183","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet","category-aspnet","category-aspnetcore"],"acf":[],"blog_post_summary":" Learn how to integrate a build process for client web assets using tools like npm and webpack into the builds of your Razor Class Libraries.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/37183","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/1866"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=37183"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/37183\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/37184"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=37183"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=37183"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=37183"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Adding a client web assets build process<\/h2>\n
\n
\n
npm install<\/code> when the packages are not available locally or when the package.json<\/em> file has been updated.<\/p>\nUsing the MicrosoftAspNetCore.ClientAssets package<\/h2>\n
\n
build:Debug<\/code> and build:Release<\/code> scripts you want to run for Debug and Release builds.<\/li>\n<\/ul>\nAdd a client web assets build process using MSBuild<\/h2>\n
Integrating
npm install<\/code> with Razor Class Libraries<\/h3>\nnpm install<\/code>. MSBuild tasks allow you to specify Inputs<\/code> and Outputs<\/code>, which are used to determine if the target needs to run by examining whether an input is newer than one of the outputs. Since we’re putting all our client sources in the assets<\/em> folder, we can use the assets\/package.json<\/em> file as an input to determine if we need to run the npm install<\/code> command or not. When npm install<\/code> is run, a node_modules\/.package-lock.json<\/em> file is created, which we can use for the output. If package.json<\/em> is changed, it will be newer than node_modules\/.package-lock.json<\/em>, which will trigger a new install the next time the build is triggered.<\/p>\n<Target Name=\"NpmInstall\" Inputs=\"assetspackage.json\" Outputs=\"assetsnode_modules.package-lock.json\">\r\n <Message Importance=\"high\" Text=\"Running npm install...\" \/>\r\n <Exec Command=\"npm install\" WorkingDirectory=\"assets\" \/>\r\n<\/Target><\/code><\/pre>\nRunning an npm command and collecting the outputs as static web assets<\/h3>\n
NpmRunBuild<\/code> target that runs the build:$(Configuration)<\/code> script in package.json<\/em> with every build (where $(Configuration)<\/code> is Release or Debug).<\/p>\nNpmRunBuild<\/code> target will do the following:<\/p>\n\n
Content<\/code> items, and link them to where they would be in the wwwroot<\/em> folder.<\/li>\nNpmRunBuild<\/code> target so that it runs after NpmInstall<\/code> but before AssignTargetPaths<\/code>. The target executes the specified npm command, and the command output is directed to $(IntermediateOutputPath)\\npm<\/em>, which normally points to obj\\Debug|Release\\net6.0<\/em>.<\/p>\n<Target Name=\"NpmRunBuild\" DependsOnTargets=\"NpmInstall\" BeforeTargets=\"AssignTargetPaths\">\r\n <Exec Command=\"npm run build:$(Configuration) -- -o $(IntermediateOutputPath)npm\" WorkingDirectory=\"assets\" \/>\r\n<\/Target><\/code><\/pre>\nContent<\/code> items and link them to the wwwroot<\/em> folder. We can do so by declaring three item groups after invoking the Exec<\/code> task as follows:<\/p>\n<ItemGroup>\r\n <_NpmOutput Include=\"$(IntermediateOutputPath)npm**\" \/>\r\n <Content Include=\"@(_NpmOutput)\" Link=\"wwwroot%(_NpmOutput.RecursiveDir)%(_NpmOutput.FileName)%(_NpmOutput.Extension)\" \/>\r\n <FileWrites Include=\"@(_NpmOutput)\" \/>\r\n<\/ItemGroup><\/code><\/pre>\n_NpmOutput<\/code> item group captures all the files in the output content. We then include these items as Content<\/code> and link them to the wwwroot<\/em> folder. Finally, we add these items to the list of FileWrites<\/code> so they can be cleaned up property.<\/p>\nInputs<\/code> and Outputs<\/code> on the target in the same way we did for the NpmInstall<\/code> target. MSBuild will check the outputs, and execute the target in two situations:<\/p>\n\n
<WriteLinesToFile File=\"$(IntermediateOutputPath)npmbuild.complete.txt\" Lines=\"@(_NpmOutput)\" \/><\/code><\/pre>\nFileWrites<\/code> as we did with the other outputs:<\/p>\n<FileWrites Include=\"$(IntermediateOutputPath)npmbuild.complete.txt\" \/><\/code><\/pre>\n<ItemGroup>\r\n <NpmBuildInputs Include=\"assets**\" Exclude=\"assetsnode_modules**\" \/>\r\n<\/ItemGroup><\/code><\/pre>\nNpmRunBuild<\/code> target as follows:<\/p>\n<ItemGroup>\r\n <NpmBuildInputs Include=\"assets**\" Exclude=\"assetsnode_modules**\" \/>\r\n<\/ItemGroup>\r\n\r\n<Target Name=\"NpmRunBuild\" DependsOnTargets=\"NpmInstall\" BeforeTargets=\"AssignTargetPaths\" Inputs=\"@(NpmBuildInputs)\" Outputs=\"$(IntermediateOutputPath)npmbuild.complete.txt\">\r\n <Exec Command=\"$(NpmCommand) -- -o $(IntermediateOutputPath)npm\" WorkingDirectory=\"assets\" \/>\r\n\r\n <ItemGroup>\r\n <_NpmOutput Include=\"$(IntermediateOutputPath)npm**\"><\/_NpmOutput>\r\n <Content Include=\"@(_NpmOutput)\" Link=\"wwwroot%(_NpmOutput.RecursiveDir)%(_NpmOutput.FileName)%(_NpmOutput.Extension)\" \/>\r\n <FileWrites Include=\"@(_NpmOutput)\" \/>\r\n <FileWrites Include=\"$(IntermediateOutputPath)npmbuild.complete.txt\" \/>\r\n <\/ItemGroup>\r\n\r\n <WriteLinesToFile File=\"$(IntermediateOutputPath)npmbuild.complete.txt\" Lines=\"@(_NpmOutput)\" \/>\r\n<\/Target><\/code><\/pre>\nAdding scripts in package.json<\/em><\/h3>\n
npm install<\/code> and npm run build:Debug<\/code> or npm run build:Release<\/code> when necessary, passing the output folder as the -o<\/code> parameter. We need to define these scripts in our package.json<\/em> to invoke the appropriate tool. To use webpack, the scripts look like this:<\/p>\n\"scripts\": {\r\n \"build:Debug\": \"webpack --mode development\",\r\n \"build:Release\": \"webpack --mode production\"\r\n}<\/code><\/pre>\nExec<\/code> task to npm run<\/code> will transparently flow into the invoked command and override the default output path.<\/p>\nReusing the MSBuild code<\/h3>\n
<PropertyGroup>\r\n <ClientAssetsDirectory Condition=\"'$(ClientAssetsDirectory)' == ''\">assets<\/ClientAssetsDirectory>\r\n <ClientAssetsRestoreInputs Condition=\"'$(ClientAssetsRestoreInputs)' == ''\">$(ClientAssetsDirectory)package-lock.json;$(ClientAssetsDirectory)package.json<ClientAssetsRestoreInputs>\r\n <ClientAssetsRestoreOutputs Condition=\"'$(ClientAssetsRestoreOutputs)' == ''\">$(ClientAssetsDirectory)node_modules.package-lock.json<ClientAssetsRestoreOutputs>\r\n <ClientAssetsRestoreCommand Condition=\"'$(ClientAssetsRestoreCommand)' == ''\">npm install<ClientAssetsRestoreCommand>\r\n <ClientAssetsBuildCommand Condition=\"'$(ClientAssetsBuildCommand)' == ''\">npm run build:$(Configuration)<ClientAssetsBuildCommand>\r\n <ClientAssetsBuildOutputParameter Condition=\"'$(ClientAssetsBuildOutputParameter)' == ''\">-o<ClientAssetsBuildOutputParameter>\r\n <ClientAssetsRestoreInputs>$(MSBuildProjectFile);$(ClientAssetsRestoreInputs)<\/ClientAssetsRestoreInputs>\r\n<\/PropertyGroup>\r\n\r\n<ItemGroup>\r\n <ClientAssetsInputs Include=\"$(ClientAssetsDirectory)**\" Exclude=\"$(DefaultItemExcludes)\" \/>\r\n<\/ItemGroup>\r\n\r\n<Target Name=\"NpmInstall\" Inputs=\"$(ClientAssetsRestoreInputs)\" Outputs=\"$(ClientAssetsRestoreOutputs)\">\r\n <Message Importance=\"high\" Text=\"Running $(ClientAssetsRestoreCommand)...\" \/>\r\n <Exec Command=\"$(ClientAssetsRestoreCommand)\" WorkingDirectory=\"$(ClientAssetsDirectory)\" \/>\r\n<\/Target>\r\n\r\n<Target Name=\"NpmRunBuild\" DependsOnTargets=\"NpmInstall\" BeforeTargets=\"AssignTargetPaths\" Inputs=\"@(ClientAssetsInputs)\" Outputs=\"$(IntermediateOutputPath)clientassetsbuild.complete.txt\">\r\n <Exec Command=\"$(ClientAssetsBuildCommand) -- $(ClientAssetsBuildOutputParameter) $(IntermediateOutputPath)clientassets\" WorkingDirectory=\"$(ClientAssetsDirectory)\" \/>\r\n\r\n <ItemGroup>\r\n <_ClientAssetsBuildOutput Include=\"$(IntermediateOutputPath)clientassets**\"><\/_ClientAssetsBuildOutput>\r\n <Content Include=\"@(_ClientAssetsBuildOutput)\" Link=\"wwwroot%(_ClientAssetsBuildOutput.RecursiveDir)%(_ClientAssetsBuildOutput.FileName)%(_ClientAssetsBuildOutput.Extension)\" \/>\r\n <FileWrites Include=\"@(_ClientAssetsBuildOutput)\" \/>\r\n <FileWrites Include=\"$(IntermediateOutputPath)clientassetsbuild.complete.txt\" \/>\r\n <\/ItemGroup>\r\n\r\n <WriteLinesToFile File=\"$(IntermediateOutputPath)clientassetsbuild.complete.txt\" Lines=\"@(_ClientAssetsBuildOutput)\" \/>\r\n<\/Target><\/code><\/pre>\n<PropertyGroup>\r\n <ClientAssetsDirectory>js<\/ClientAssetsDirectory>\r\n <DefaultItemExcludes>$(ClientAssetsDirectory)dist**<\/DefaultItemExcludes>\r\n<\/PropertyGroup><\/code><\/pre>\nSummary<\/h2>\n