100% found this document useful (1 vote)

1K views

Blazor PDF

Uploaded by

Rony Olazabal

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

1K views

Blazor PDF

Uploaded by

Rony Olazabal

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 64

Blazor for ASP.NET Web Forms developers e-book

Introduction
Architecture comparison
Hosting models
Project structure
Startup
Components
Pages, routing, and layouts
State management
Forms and validation
Dealing with data
Middleware
Configuration
Security
Migration
Blazor for ASP.NET Web Forms Developers
10/1/2019 • 4 minutes to read • Edit Online

IMPORTANT
PREVIEW EDITION
This article provides early content from a book that is currently under construction. If you have any feedback, submit it at
https://aka.ms/ebookfeedback.
DOWNLOAD available at: https://aka.ms/blazor-ebook

PUBLISHED BY
Microsoft Developer Division, .NET, and Visual Studio product teams
A division of Microsoft Corporation
One Microsoft Way
Redmond, Washington 98052-6399
Copyright © 2019 by Microsoft Corporation
All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any
means without the written permission of the publisher.
This book is provided "as-is" and expresses the author's views and opinions. The views, opinions and information
expressed in this book, including URL and other Internet website references, may change without notice.
Some examples depicted herein are provided for illustration only and are fictitious. No real association or
connection is intended or should be inferred.
Microsoft and the trademarks listed at https://www.microsoft.com on the "Trademarks" webpage are trademarks of
the Microsoft group of companies.
Mac and macOS are trademarks of Apple Inc.
All other marks and logos are property of their respective owners.
Authors:

Daniel Roth, Principal Program Manager, Microsoft Corp.

Jeff Fritz, Senior Program Manager, Microsoft Corp.

Taylor Southwick, Senior Software Engineer, Microsoft Corp.

Scott Addie, Senior Content Developer, Microsoft Corp.

Introduction
.NET has long supported web app development through ASP.NET, a comprehensive set of frameworks and tools
for building any kind of web app. ASP.NET has its own lineage of web frameworks and technologies starting all
the way back with classic Active Server Pages (ASP ). Frameworks like ASP.NET Web Forms, ASP.NET MVC,
ASP.NET Web Pages, and more recently ASP.NET Core, provide a productive and powerful way to build server-
rendered web apps, where UI content is dynamically generated on the server in response to HTTP requests. Each
ASP.NET framework caters to a different audience and app building philosophy. ASP.NET Web Forms shipped
with the original release of the .NET Framework and enabled web development using many of the patterns familiar
to desktop developers, like reusable UI controls with simple event handling. However, none of the ASP.NET
offerings provide a way to run code that executed in the user's browser. To do that requires writing JavaScript and
using any of the many JavaScript frameworks and tools that have phased in and out of popularity over the years:
jQuery, Knockout, Angular, React, and so on.
Blazor is a new web framework that changes what is possible when building web apps with .NET. Blazor is a client-
side web UI framework based on C# instead of JavaScript. With Blazor you can write your client-side logic and UI
components in C#, compile them into normal .NET assemblies, and then run them directly in the browser using a
new open web standard called WebAssembly. Or alternatively, Blazor can run your .NET UI components on the
server and handle all UI interactions fluidly over a real-time connection with the browser. When paired with .NET
running on the server, Blazor enables full-stack web development with .NET. While Blazor shares many
commonalities with ASP.NET Web Forms, like having a reusable component model and a simple way to handle
user events, it also builds on the foundations of .NET Core to provide a modern and high performance web
development experience.
This book introduces ASP.NET Web Forms developers to Blazor in a way that is familiar and convenient. It
introduces Blazor concepts in parallel with analogous concepts in ASP.NET Web Forms while also explaining new
concepts that may be less familiar. It covers a broad range of topics and concerns including component authoring,
routing, layout, configuration, and security. And while the content of this book is primarily for enabling new
development, it also covers guidelines and strategies for migrating existing ASP.NET Web Forms to Blazor for
when you want to modernize an existing app.

Who should use the book

This book is for ASP.NET Web Forms developers looking for an introduction to Blazor that relates to their existing
knowledge and skills. This book can help with quickly getting started on a new Blazor-based project or to help
chart a roadmap for modernizing an existing ASP.NET Web Forms application.

How to use the book

The first part of this book covers what Blazor is and compares it to web app development with ASP.NET Web
Forms. The book then covers a variety of Blazor topics, chapter by chapter, and relates each Blazor concept to the
corresponding concept in ASP.NET Web Forms, or explains fully any completely new concepts. The book also
refers regularly to a complete sample app implemented in both ASP.NET Web Forms and Blazor to demonstrate
Blazor features and to provide a case study for migrating from ASP.NET Web Forms to Blazor. You can find both
implementations of the sample app (ASP.NET Web Forms and Blazor versions) on GitHub.

What this book doesn't cover

This book is an introduction to Blazor, not a comprehensive migration guide. While it does include guidance on
how to approach migrating a project from ASP.NET Web Forms to Blazor, it does not attempt to cover every
nuance and detail. For more general guidance on migrating from ASP.NET to ASP.NET Core, refer to the
migration guidance in the ASP.NET Core documentation.
Additional resources
You can find the official Blazor home page and documentation at https://blazor.net.

Send your feedback

This book and related samples are constantly evolving, so your feedback is welcomed! If you have comments
about how this book can be improved, use the feedback section at the bottom of any page built on GitHub issues.

NEXT
An introduction to Blazor for ASP.NET Web Forms
developers
9/23/2019 • 8 minutes to read • Edit Online

The ASP.NET Web Forms framework has been a staple of .NET web development since the .NET Framework first
shipped in 2002. Back when the Web was still largely in its infancy, ASP.NET Web Forms made building web apps
simple and productive by adopting many of the patterns that were used for desktop development. In ASP.NET
Web Forms, web pages can be quickly composed from reusable UI controls. User interactions are handled
naturally as events. There's a rich ecosystem of Web Forms UI controls provided by Microsoft and control vendors.
The controls ease the efforts of connecting to data sources and displaying rich data visualizations. For the visually
inclined, the Web Forms designer provides a simple drag-and-drop interface for managing controls.
Over the years, Microsoft has introduced new ASP.NET-based web frameworks to address web development
trends. Some such web frameworks include ASP.NET MVC, ASP.NET Web Pages, and more recently ASP.NET
Core. With each new framework, some have predicted the imminent decline of ASP.NET Web Forms and criticized
it as an outdated, outmoded web framework. Despite these predictions, many .NET web developers continue to
find ASP.NET Web Forms a simple, stable, and productive way to get their work done.
At the time of writing, almost half a million web developers use ASP.NET Web Forms every month. The ASP.NET
Web Forms framework is stable to the point that docs, samples, books, and blog posts from a decade ago remain
useful and relevant. For many .NET web developers, "ASP.NET" is still synonymous with "ASP.NET Web Forms"
as it was when .NET was first conceived. Arguments on the pros and cons of ASP.NET Web Forms compared to
the other new .NET web frameworks may rage on. ASP.NET Web Forms remains a popular framework for
creating web apps.
Even so, innovations in software development aren't slowing. All software developers need to stay abreast of new
technologies and trends. Two trends in particular are worth considering:
1. The shift to open-source and cross-platform
2. The shift of app logic to the client

An open-source and cross-platform .NET

When .NET and ASP.NET Web Forms first shipped, the platform ecosystem looked much different than it does
today. The desktop and server markets were dominated by Windows. Alternative platforms like macOS and Linux
were still struggling to gain traction. ASP.NET Web Forms ships with the .NET Framework as a Windows-only
component, which means ASP.NET Web Forms apps can only run on Windows Server machines. Many modern
environments now use different kinds of platforms for servers and development machines such that cross-
platform support for many users is an absolute requirement.
Most modern web frameworks are now also open-source, which has a number of benefits. Users aren't beheld to a
single project owner to fix bugs and add features. Open-source projects provide improved transparency on
development progress and upcoming changes. Open-source projects enjoy contributions from an entire
community, and they foster a supportive open-source ecosystem. Despite the risks of open-source, many
consumers and contributors have found suitable mitigations that enable them to enjoy the benefits of an open-
source ecosystem in a safe and reasonable way. Examples of such mitigations include contributor license
agreements, friendly licenses, pedigree scans, and supporting foundations.
The .NET community has embraced both cross-platform support and open-source. .NET Core is an open-source
and cross-platform implementation of .NET that runs on a plethora of platforms, including Windows, macOS, and
various Linux distributions. Xamarin provides Mono, an open-source version of .NET. Mono runs on Android, iOS,
and a variety of other form factors, including watches and smart TVs. Microsoft has announced that .NET 5 will
reconcile .NET Core and Mono into "a single .NET runtime and framework that can be used everywhere and that
has uniform runtime behaviors and developer experiences."
Will ASP.NET Web Forms benefit from the move to open-source and cross-platform support? The answer,
unfortunately, is no, or at least not to the same extent as the rest of the platform. The .NET team recently made it
clear that ASP.NET Web Forms won't be ported to .NET Core or .NET 5. Why is that?
There were efforts in the early days of .NET Core to port ASP.NET Web Forms. The number of breaking changes
required were found to be too drastic. There's also an admission here that even for Microsoft, there's a limit to the
number of web frameworks that it can support simultaneously. Perhaps someone in the community will take up
the cause of creating an open-source and cross-platform version of ASP.NET Web Forms. The source code for
ASP.NET Web Forms has been made available publicly in reference form. But for the time being, it seems
ASP.NET Web Forms will remain Windows-only and without an open-source contribution model. If cross-
platform support or open-source become important for your scenarios, then you'll need to look for something
new.
Does this mean ASP.NET Web Forms is dead and should no longer be used? Of course not! As long as the .NET
Framework ships as part of Windows, ASP.NET Web Forms will be a supported framework. For many Web Forms
developers, the lack of cross-platform and open-source support is a non-issue. If you don't have a requirement for
cross-platform support, open-source, or any of the other new features in .NET Core or .NET 5, then sticking with
ASP.NET Web Forms on Windows is fine. ASP.NET Web Forms will continue to be a productive way to write web
apps for many years to come.
But there's another trend worth considering, and that's the shift to the client.

Client-side web development

All of the .NET-based web frameworks, including ASP.NET Web Forms, have historically had one thing in
common: they're server-rendered. In server-rendered web apps, the browser makes a request to the server, which
executes some code (.NET code in ASP.NET apps) to produce a response. That response is sent back to the
browser to handle. In this model, the browser is used as a thin rendering engine. The hard work of producing the
UI, running the business logic, and managing state occurs on the server.
However, browsers have become versatile platforms. They implement an ever-increasing number of open web
standards that grant access to the capabilities of the user's machine. Why not take advantage of the compute
power, storage, memory, and other resources of the client device? UI interactions in particular can benefit from a
richer and more interactive feel when handled at least partially or completely client-side. Logic and data that
should be handled on the server can still be handled server-side. Web API calls or even over real-time protocols,
like WebSockets, can be used. These benefits are available to web developers for free if they're willing to write
JavaScript. Client-side UI frameworks, such as Angular, React, and Vue, simplify client-side web development and
have grown in popularity. ASP.NET Web Forms developers can also benefit from leveraging the client, and even
have some out-of-the-box support with integrated JavaScript frameworks like ASP.NET AJAX.
But bridging two different platforms and ecosystems (.NET and JavaScript) comes with a cost. Expertise is required
in two parallel worlds with different languages, frameworks, and tools. Code and logic can't be easily shared
between client and server, resulting in duplication and engineering overhead. It can also be difficult to keep up with
the JavaScript ecosystem, which has a history of evolving at breakneck speed. Front-end framework and build tool
preferences change quickly. The industry has observed the progression from Grunt to Gulp to Webpack, and so
on. The same restless churn has occurred with front-end frameworks such as jQuery, Knockout, Angular, React,
and Vue. But given JavaScript's browser monopoly, there was little choice in the matter. That is, until the web
community got together and caused a miracle to happen!

WebAssembly fulfills a need

In 2015, the major browser vendors joined forces in a W3C Community Group to create a new open web standard
called WebAssembly. WebAssembly is a byte code for the Web. If you can compile your code to WebAssembly, it
can then run on any browser on any platform at near native speed. Initial efforts focused on C/C++. The result was
a dramatic demonstration of running native 3D graphics engines directly in the browser without plugins.
WebAssembly has since been standardized and implemented by all major browsers.
Work on running .NET on WebAssembly was announced in late 2017 and is expected to ship in 2020, including
support from .NET 5. The ability to run .NET code directly in the browser enables full-stack web development with
.NET.

Blazor: full-stack web development with .NET

On its own, the ability to run .NET code in a browser doesn't provide an end-to-end experience for creating client-
side web apps. That's where Blazor comes in. Blazor is a client-side web UI framework based on C# instead of
JavaScript. Blazor can run directly in the browser via WebAssembly. No browser plugins are required.
Alternatively, Blazor apps can run server-side on .NET Core and handle all user interactions over a real-time
connection with the browser.
Blazor has great tooling support in Visual Studio and Visual Studio Code. The framework also includes a full UI
component model and has built-in facilities for:
Forms and validation
Dependency injection
Client-side routing
Layouts
In-browser debugging
JavaScript interop
Blazor has a lot in common with ASP.NET Web Forms. Both frameworks offer component-based, event-driven,
stateful UI programming models. The main architectural difference is that ASP.NET Web Forms runs only on the
server. Blazor can run on the client in the browser. But if you're coming from an ASP.NET Web Forms background,
there's a lot in Blazor that will feel familiar. Blazor is a natural solution for ASP.NET Web Forms developers looking
for a way to take advantage of client-side development and the open-source, cross-platform future of .NET.
This book provides an introduction to Blazor that is catered specifically to ASP.NET Web Forms developers. Each
Blazor concept is presented in the context of analogous ASP.NET Web Forms features and practices. By the end of
this book, you'll have an understanding of:
How to build Blazor apps.
How Blazor works.
How Blazor relates to .NET Core.
Reasonable strategies for migrating existing ASP.NET Web Forms apps to Blazor where appropriate.

Get started with Blazor

Getting started with Blazor is easy. Go to https://blazor.net and follow the links to install the appropriate .NET Core
SDK and Blazor project templates. You'll also find instructions for setting up the Blazor tooling in Visual Studio or
Visual Studio Code.

P R E V IO U S NEXT
Architecture comparison of ASP.NET Web Forms and
Blazor
9/23/2019 • 3 minutes to read • Edit Online

While ASP.NET Web Forms and Blazor have many similar concepts, there are differences in how they work. This
chapter examines the inner workings and architectures of ASP.NET Web Forms and Blazor.

ASP.NET Web Forms

The ASP.NET Web Forms framework is based on a page-centric architecture. Each HTTP request for a location in
the app is a separate page with which ASP.NET responds. As pages are requested, the contents of the browser are
replaced with the results of the page requested.
Pages consist of the following components:
HTML markup
C# or Visual Basic code
A code-behind class containing logic and event-handling capabilities
Controls
Controls are reusable units of web UI that can be programmatically placed and interacted with on a page. Pages
are composed of files that end with .aspx containing markup, controls, and some code. The code-behind classes are
in files with the same base name and an .aspx.cs or .aspx.vb extension, depending on the programming language
used. Interestingly, the web server interprets contents of the .aspx files and compiles them whenever they change.
This recompilation occurs even if the web server is already running.
Controls can be built with markup and delivered as user controls. A user control derives from the UserControl
class and has a similar structure to the Page. Markup for user controls is stored in an .ascx file. An accompanying
code-behind class resides in an .ascx.cs or .ascx.vb file. Controls can also be built completely with code, by
inheriting from either the WebControl or CompositeControl base class.
Pages also have an extensive event lifecycle. Each page raises events for the initialization, load, prerender, and
unload events that occur as the ASP.NET runtime executes the page's code for each request.
Controls on a Page typically post-back to the same page that presented the control, and carry along with them a
payload from a hidden form field called ViewState . The ViewState field contains information about the state of
the controls at the time they were rendered and presented on the page, allowing the ASP.NET runtime to compare
and identify changes in the content submitted to the server.

Blazor
Blazor is a client-side web UI framework similar in nature to JavaScript front-end frameworks like Angular or
React. Blazor handles user interactions and renders the necessary UI updates. Blazor isn't based on a request-reply
model. User interactions are handled as events that aren't in the context of any particular HTTP request.
Blazor apps consist of one or more root components that are rendered on an HTML page.

How the user specifies where components should render and how the components are then wired up for user
interactions is hosting model specific.
Blazor components are .NET classes that represent a reusable piece of UI. Each component maintains its own state
and specifies its own rendering logic, which can include rendering other components. Components specify event
handlers for specific user interactions to update the component's state.
After a component handles an event, Blazor renders the component and keeps track of what changed in the
rendered output. Components don't render directly to the Document Object Model (DOM ). They instead render to
an in-memory representation of the DOM called a RenderTree so that Blazor can track the changes. Blazor
compares the newly rendered output with the previous output to calculate a UI diff that it then applies efficiently to
the DOM.

Components can also manually indicate that they should be rendered if their state changes outside of a normal UI
event. Blazor uses a SynchronizationContext to enforce a single logical thread of execution. A component's lifecycle
methods and any event callbacks that are raised by Blazor are executed on this SynchronizationContext .

P R E V IO U S NEXT
Blazor app hosting models
9/23/2019 • 5 minutes to read • Edit Online

Blazor apps can be hosted in IIS just like ASP.NET Web Forms apps. Blazor apps can also be hosted in one of the
following ways:
Client-side in the browser on WebAssembly.
Server-side in an ASP.NET Core app.

Blazor WebAssembly apps

Blazor WebAssembly apps execute directly in the browser on a WebAssembly-based .NET runtime. Blazor
WebAssembly apps function in a similar way to front-end JavaScript frameworks like Angular or React. However,
instead of writing JavaScript you write C#. The .NET runtime is downloaded with the app along with the app
assembly and any required dependencies. No browser plugins or extensions are required.
The downloaded assemblies are normal .NET assemblies, like you would use in any other .NET app. Because the
runtime supports .NET Standard, you can use existing .NET Standard libraries with your Blazor WebAssembly
app. However, these assemblies will still execute in the browser security sandbox. Some functionality may throw a
PlatformNotSupportedException, like trying to access the file system or opening arbitrary network connections.
When the app loads, the .NET runtime is started and pointed at the app assembly. The app startup logic runs, and
the root components are rendered. Blazor calculates the UI updates based on the rendered output from the
components. The DOM updates are then applied.

Blazor WebAssembly apps run purely client-side. Such apps can be deployed to static site hosting solutions like
GitHub Pages or Azure Static Website Hosting. .NET isn't required on the server at all. Deep linking to parts of the
app typically requires a routing solution on the server. The routing solution redirects requests to the root of the
app. For example, this redirection can be handled using URL rewrite rules in IIS.
To get all the benefits of Blazor and full-stack .NET web development, host your Blazor WebAssembly app with
ASP.NET Core. By using .NET on both the client and server, you can easily share code and build your app using
one consistent set of languages, frameworks, and tools. Blazor provides convenient templates for setting up a
solution that contains both a Blazor WebAssembly app and an ASP.NET Core host project. When the solution is
built, the built static files from the Blazor app are hosted by the ASP.NET Core app with fallback routing already
setup.

Blazor Server apps

Recall from the Blazor architecture discussion that Blazor components render their output to an intermediate
abstraction called a RenderTree . The Blazor framework then compares what was rendered with what was
previously rendered. The differences are applied to the DOM. Blazor components are decoupled from how their
rendered output is applied. Consequently, the components themselves don't have to run in the same process as
the process updating the UI. In fact, they don't even have to run on the same machine.
In Blazor Server apps, the components run on the server instead of client-side in the browser. UI events that occur
in the browser are sent to the server over a real-time connection. The events are dispatched to the correct
component instances. The components render, and the calculated UI diff is serialized and sent to the browser
where it's applied to the DOM.

The Blazor Server hosting model may sound familiar if you've used ASP.NET AJAX and the UpdatePanel control.
The UpdatePanel control handles applying partial page updates in response to trigger events on the page. When
triggered, the UpdatePanel requests a partial update and then applies it without needing to refresh the page. The
state of the UI is managed using ViewState . Blazor Server apps are slightly different in that the app requires an
active connection with the client. Additionally, all UI state is maintained on the server. Aside from those
differences, the two models are conceptually similar.

How to choose the right Blazor hosting model

As described in the Blazor hosting model docs, the different Blazor hosting models have different tradeoffs.
The Blazor WebAssembly hosting model has the following benefits:
There's no .NET server-side dependency. The app is fully functioning after downloaded to the client.
Client resources and capabilities are fully leveraged.
Work is offloaded from the server to the client.
An ASP.NET Core web server isn't required to host the app. Serverless deployment scenarios are possible (for
example, serving the app from a CDN ).
The downsides of the Blazor WebAssembly hosting model are:
Browser capabilities restrict the app.
Capable client hardware and software (for example, WebAssembly support) is required.
Download size is larger, and apps take longer to load.
.NET runtime and tooling support is less mature. For example, there are limitations in .NET Standard support
and debugging.
Conversely, the Blazor Server hosting model offers the following benefits:
Download size is much smaller than a client-side app, and the app loads much faster.
The app takes full advantage of server capabilities, including use of any .NET Core-compatible APIs.
.NET Core on the server is used to run the app, so existing .NET tooling, such as debugging, works as expected.
Thin clients are supported. For example, server-side apps work with browsers that don't support WebAssembly
and on resource-constrained devices.
The app's .NET/C# code base, including the app's component code, isn't served to clients.
The downsides to the Blazor Server hosting model are:
Higher UI latency. Every user interaction involves a network hop.
There's no offline support. If the client connection fails, the app stops working.
Scalability is challenging for apps with many users. The server must manage multiple client connections and
handle client state.
An ASP.NET Core server is required to serve the app. Serverless deployment scenarios aren't possible. For
example, you can't serve the app from a CDN.
The preceding list of trade-offs may be intimidating, but your hosting model can be changed later. Regardless of
the Blazor hosting model selected, the component model is the same. In principle, the same components can be
used with either hosting model. Your app code doesn't change; however, it's a good practice to introduce
abstractions so that your components stay hosting model-agnostic. The abstractions allow your app to more easily
adopt a different hosting model.

Deploy your app

ASP.NET Web Forms apps are typically hosted on IIS on a Windows Server machine or cluster. Blazor apps can
also:
Be hosted on IIS, either as static files or as an ASP.NET Core app.
Leverage ASP.NET Core's flexibility to be hosted on various platforms and server infrastructures. For example,
you can host a Blazor App using Nginx or Apache on Linux. For more information about how to publish and
deploy Blazor apps, see the Blazor Hosting and deployment documentation.
In the next section, we'll look at how the projects for Blazor WebAssembly and Blazor Server apps are set up.

P R E V IO U S NEXT
Project structure for Blazor apps
9/23/2019 • 8 minutes to read • Edit Online

Despite their significant project structure differences, ASP.NET Web Forms and Blazor share many similar
concepts. Here, we'll look at the structure of a Blazor project and compare it to an ASP.NET Web Forms project.
To create your first Blazor app, follow the instructions in the Blazor getting started steps. You can follow the
instructions to create either a Blazor Server app or a Blazor WebAssembly app hosted in ASP.NET Core. Except for
the hosting model-specific logic, most of the code in both projects is the same.

Project file
Blazor Server apps are .NET Core projects. The project file for the Blazor Server app is about as simple as it can
get:

<PropertyGroup>
<TargetFramework>netcoreapp3.0</TargetFramework>
</PropertyGroup>

</Project>

The project file for a Blazor WebAssembly app looks slightly more involved (exact version numbers may vary):

<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<RazorLangVersion>3.0</RazorLangVersion>
</PropertyGroup>

</Project>

Blazor WebAssembly projects target .NET Standard instead of .NET Core because they run in the browser on a
WebAssembly-based .NET runtime. You can't install .NET into a web browser like you can on a server or developer
machine. Consequently, the project references the Blazor framework using individual package references.
By comparison, a default ASP.NET Web Forms project includes almost 300 lines of XML in its .csproj file, most of
which is explicitly listing the various code and content files in the project. Many of the simplifications in the .NET
Core- and .NET Standard-based projects come from the default targets and properties imported by referencing
the Microsoft.NET.Sdk.Web SDK, often referred to as simply the Web SDK. The Web SDK includes wildcards and
other conveniences that simplify inclusion of code and content files in the project. You don't need to list the files
explicitly. When targeting .NET Core, the Web SDK also adds framework references to both the .NET Core and
ASP.NET Core shared frameworks. The frameworks are visible from the Dependencies > Frameworks node in
the Solution Explorer window. The shared frameworks are collections of assemblies that were installed on the
machine when installing .NET Core.
Although they're supported, individual assembly references are less common in .NET Core projects. Most project
dependencies are handled as NuGet package references. You only need to reference top-level package
dependencies in .NET Core projects. Transitive dependencies are included automatically. Instead of using the
packages.config file commonly found in ASP.NET Web Forms projects to reference packages, package references
are added to the project file using the <PackageReference> element.

Entry point
The Blazor Server app's entry point is defined in the Program.cs file, as you would see in a Console app. When the
app executes, it creates and runs a web host instance using defaults specific to web apps. The web host manages
the Blazor Server app's lifecycle and sets up host-level services. Examples of such services are configuration,
logging, dependency injection, and the HTTP server. This code is mostly boilerplate and is often left unchanged.

public class Program

{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>

Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}

Blazor WebAssembly apps also define an entry point in Program.cs. The code looks slightly different. The code is
similar in that it's setting up the app host to provide the same host-level services to the app. The WebAssembly
app host doesn't, however, set up an HTTP server because it executes directly in the browser.
Blazor apps have a Startup class instead of a Global.asax file to define the startup logic for the app. The Startup
class is used to configure the app and any app-specific services. In the Blazor Server app, the Startup class is used
to set up the endpoint for the real-time connection used by Blazor between the client browsers and the server. In
the Blazor WebAssembly app, the Startup class defines the root components for the app and where they should
be rendered. We'll take a deeper look at the Startup class in the App startup section.

Static files
Unlike ASP.NET Web Forms projects, not all files in a Blazor project can be requested as static files. Only the files
in the wwwroot folder are web-addressable. This folder is referred to the app's "web root". Anything outside of the
app's web root isn't web-addressable. This setup provides an additional level of security that prevents accidental
exposing of project files over the web.

Configuration
Configuration in ASP.NET Web Forms apps is typically handled using one or more web.config files. Blazor apps
don't typically have web.config files. If they do, the file is only used to configure IIS -specific settings when hosted
on IIS. Instead, Blazor Server apps use the ASP.NET Core configuration abstractions (Blazor WebAssembly apps
don't currently support the same configuration abstractions, but that may be a feature added in the future). For
example, the default Blazor Server app stores some settings in appsettings.json.

{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}

We'll learn more about configuration in ASP.NET Core projects in the Configuration section.

Razor components
Most files in Blazor projects are .razor files. Razor is a templating language based on HTML and C# that is used to
dynamically generate web UI. The .razor files define components that make up the UI of the app. For the most
part, the components are identical for both the Blazor Server and Blazor WebAssembly apps. Components in
Blazor are analogous to user controls in ASP.NET Web Forms.
Each Razor component file is compiled into a .NET class when the project is built. The generated class captures the
component's state, rendering logic, lifecycle methods, event handlers, and other logic. We'll look at authoring
components in the Building reusable UI components with Blazor section.
The _Imports.razor files aren't Razor component files. Instead, they define a set of Razor directives to import into
other .razor files within the same folder and in its subfolders. For example, a _Imports.razor file is a conventional
way to add using statements for commonly used namespaces:

@using System.Net.Http
@using Microsoft.AspNetCore.Authorization
@using Microsoft.AspNetCore.Components.Authorization
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using Microsoft.JSInterop
@using BlazorApp1
@using BlazorApp1.Shared

Pages
Where are the pages in the Blazor apps? Blazor doesn't define a separate file extension for addressable pages, like
the .aspx files in ASP.NET Web Forms apps. Instead, pages are defined by assigning routes to components. A
route is typically assigned using the @page Razor directive. For example, the Counter component authored in the
Pages/Counter.razor file defines the following route:

@page "/counter"

Routing in Blazor is handled client-side, not on the server. As the user navigates in the browser, Blazor intercepts
the navigation and then renders the component with the matching route.
The component routes aren't currently inferred by the component's file location like they are with .aspx pages. This
feature may be added in the future. Each route must be specified explicitly on the component. Storing routable
components in a Pages folder has no special meaning and is purely a convention.
We'll look in greater detail at routing in Blazor in the Pages, routing, and layouts section.

Layout
In ASP.NET Web Forms apps, common page layout is handled using master pages (Site.Master). In Blazor apps,
page layout is handled using layout components (Shared/MainLayout.razor). Layout components will be
discussed in more detail in Page, routing, and layouts section.

Bootstrap Blazor
To bootstrap Blazor, the app must:
Specify where on the page the root component (App.Razor) should be rendered.
Add the corresponding Blazor framework script.
In the Blazor Server app, the root component's host page is defined in the _Host.cshtml file. This file defines a
Razor Page, not a component. Razor Pages use Razor syntax to define a server-addressable page, very much like
an .aspx page. The Html.RenderComponentAsync<TComponent>(RenderMode) method is used to define where a root-level
component should be rendered. The RenderMode option indicates the manner in which the component should be
rendered. The following table outlines the supported RenderMode options.

OPTION DESCRIPTION

RenderMode.Server Rendered interactively once a connection with the browser is

established

RenderMode.ServerPrerendered First prerendered and then rendered interactively

RenderMode.Static Rendered as static content

The script reference to _framework/blazor.server.js establishes the real-time connection with the server and then
deals with all user interactions and UI updates.
@page "/"
@namespace BlazorApp1.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>BlazorApp1</title>
<base href="~/" />
<link rel="stylesheet" href="css/bootstrap/bootstrap.min.css" />
<link href="css/site.css" rel="stylesheet" />
</head>
<body>
<app>
@(await Html.RenderComponentAsync<App>(RenderMode.ServerPrerendered))
</app>

In the Blazor WebAssembly app, the host page is a simple static HTML file under wwwroot/index.html. The <app>
element is used to indicate where the root component should be rendered.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>BlazorApp2</title>
<base href="/" />
<link href="css/bootstrap/bootstrap.min.css" rel="stylesheet" />
<link href="css/site.css" rel="stylesheet" />
</head>
<body>
<app>Loading...</app>

The specific component to render is configured in the app's Startup.Configure method with a corresponding CSS
selector indicating where the component should be rendered.

public class Startup

{
public void ConfigureServices(IServiceCollection services)
{
}

public void Configure(IComponentsApplicationBuilder app)

{
app.AddComponent<App>("app");
}
}

Build output
When a Blazor project is built, all Razor component and code files are compiled into a single assembly. Unlike
ASP.NET Web Forms projects, Blazor doesn't support runtime compilation of the UI logic.

Run the app

To run the Blazor Server app, press F5 in Visual Studio. Blazor apps don't support runtime compilation. To see the
results of code and component markup changes, rebuild and restart the app with the debugger attached. If you
run without the debugger attached ( Ctrl+F5 ), Visual Studio watches for file changes and restarts the app as
changes are made. You manually refresh the browser as changes are made.
To run the Blazor WebAssembly app, choose one of the following approaches:
Run the client project directly using the development server.
Run the server project when hosting the app with ASP.NET Core.
Blazor WebAssembly apps don't support debugging using Visual Studio. To run the app, use Ctrl+F5 instead of
F5 . You can instead debug Blazor WebAssembly apps directly in the browser. See Debug ASP.NET Core Blazor
for details.

P R E V IO U S NEXT
App startup
9/23/2019 • 2 minutes to read • Edit Online

This content is coming soon.

P R E V IO U S NEXT
Build reusable UI components with Blazor
10/8/2019 • 16 minutes to read • Edit Online

One of the beautiful things about ASP.NET Web Forms is how it enables encapsulation of reusable pieces of user
interface (UI) code into reusable UI controls. Custom user controls can be defined in markup using .ascx files. You
can also build elaborate server controls in code with full designer support.
Blazor also supports UI encapsulation through components. A component:
Is a self-contained chunk of UI.
Maintains its own state and rendering logic.
Can define UI event handlers, bind to input data, and manage its own lifecycle.
Is typically defined in a .razor file using Razor syntax.

An introduction to Razor
Razor is a light-weight markup templating language based on HTML and C#. With Razor, you can seamlessly
transition between markup and C# code to define your component rendering logic. When the .razor file is
compiled, the rendering logic is captured in a structured way in a .NET class. The name of the compiled class is
taken from the .razor file name. The namespace is taken from the default namespace for the project and the folder
path, or you can explicitly specify the namespace using the @namespace directive (more on Razor directives below ).
A component's rendering logic is authored using normal HTML markup with dynamic logic added using C#. The
@ character is used to transition to C#. Razor is typically smart about figuring out when you've switched back to
HTML. For example, the following component renders a <p> tag with the current time:

<p>@DateTime.Now</p>

To explicitly specify the beginning and ending of a C# expression, use parentheses:

<p>@(DateTime.Now)</p>

Razor also makes it easy to use C# control flow in your rendering logic. For example, you can conditionally render
some HTML like this:

@if (value % 2 == 0)
{
<p>The value was even.</p>
}

Or you can generate a list of items using a normal C# foreach loop like this:
<ul>
@foreach (var item in items)
{
<li>item.Text</li>
}
</ul>

Razor directives, like directives in ASP.NET Web Forms, control many aspects of how a Razor component is
compiled. Examples include the component's:
Namespace
Base class
Implemented interfaces
Generic parameters
Imported namespaces
Routes
Razor directives start with the @ character and are typically used at the start of a new line at the start of the file.
For example, the @namespace directive defines the component's namespace:

@namespace MyComponentNamespace

The following table summarizes the various Razor directives used in Blazor and their ASP.NET Web Forms
equivalents, if they exist.

DIRECTIVE DESCRIPTION EXAMPLE WEB FORMS EQUIVALENT

@attribute Adds a class-level attribute @attribute [Authorize] None

to the component

@code Adds class members to the @code { ... } <script

component runat="server">...
</script>

@implements Implements the specified @implements IDisposable Use code-behind

interface

@inherits Inherits from the specified @inherits <%@ Control

base class MyComponentBase Inherits="MyUserControlBase"
%>

@inject Injects a service into the @inject IJSRuntime JS None

component

@layout Specifies a layout @layout MainLayout <%@ Page

component for the MasterPageFile="~/Site.Master"
%>
component

@namespace Sets the namespace for the @namespace MyNamespace None

component

@page Specifies the route for the @page "/product/{id}" <%@ Page %>
component
DIRECTIVE DESCRIPTION EXAMPLE WEB FORMS EQUIVALENT

@typeparam Specifies a generic type @typeparam TItem Use code-behind

parameter for the
component

@using Specifies a namespace to @using Add namespace in

bring into scope MyComponentNamespace web.config

Razor components also make extensive use of directive attributes on elements to control various aspects of how
components get compiled (event handling, data binding, component & element references, and so on). Directive
attributes all follow a common generic syntax where the values in parenthesis are optional:

@directive(-suffix(:name))(="value")

The following table summarizes the various attributes for Razor directives used in Blazor.

ATTRIBUTE DESCRIPTION EXAMPLE

@attributes Renders a dictionary of attributes <input

@attributes="ExtraAttributes" />

@bind Creates a two-way data binding <input @bind="username"

@bind:event="oninput" />

@on{event} Adds an event handler for the specified <button

event @onclick="IncrementCount">Click
me!</button>

@key Specifies a key to be used by the diffing <DetailsEditor @key="person"

algorithm for preserving elements in a Details="person.Details" />
collection

@ref Captures a reference to the component <MyDialog @ref="myDialog" />

or HTML element

The various directive attributes used by Blazor ( @onclick , @bind , @ref , and so on) are covered in the sections
below and later chapters.
Many of the syntaxes used in .aspx and .ascx files have parallel syntaxes in Razor. Below is a simple comparison of
the syntaxes for ASP.NET Web Forms and Razor.

FEATURE WEB FORMS SYNTAX RAZOR SYNTAX

Directives <%@ [directive] <%@ Page %> @[directive] @page

Code blocks <% %> <% int x = 123; @{ } @{ int x = 123; }

Expressions <%: %> <%:DateTime.Now Implicit: @ @DateTime.Now

(HTML-encoded) %> Explicit: @() @(DateTime.Now)

Comments <%-- --%> <%-- Commented -- @* @ @ Commented *@

%>
FEATURE WEB FORMS SYNTAX RAZOR SYNTAX

Data binding <%# %> <%# Bind("Name") @bind <input

%> @bind="username"
/>

To add members to the Razor component class, use the @code directive. This technique is similar to using a
<script runat="server">...</script> block in an ASP.NET Web Forms user control or page.

@code {
int count = 0;

void IncrementCount()
{
count++;
}
}

Because Razor is based on C#, it must be compiled from within a C# project (.csproj). You can't compile .razor files
from a VB project (.vbproj). You can still reference VB projects from your Blazor project. The opposite is true too.
For a full Razor syntax reference, see Razor syntax reference for ASP.NET Core.

Use components
Aside from normal HTML, components can also use other components as part of their rendering logic. The syntax
for using a component in Razor is similar to using a user control in an ASP.NET Web Forms app. Components are
specified using an element tag that matches the type name of the component. For example, you can add a
Counter component like this:

Unlike ASP.NET Web Forms, components in Blazor:

Don't use an element prefix (for example, asp: ).
Don't require registration on the page or in the web.config.
Think of Razor components like you would .NET types, because that's exactly what they are. If the assembly
containing the component is referenced, then the component is available for use. To bring the component's
namespace into scope, apply the @using directive:

@using MyComponentLib

As seen in the default Blazor projects, it's common to put @using directives into a _Imports.razor file so that
they're imported into all .razor files in the same directory and in child directories.
If the namespace for a component isn't in scope, you can specify a component using its full type name, as you can
in C#:

<MyComponentLib.Counter />

Component parameters
In ASP.NET Web Forms, you can flow parameters and data to controls using public properties. These properties
can be set in markup using attributes or set directly in code. Blazor components work in a similar fashion,
although the component properties must also be marked with the [Parameter] attribute to be considered
component parameters.
The following Counter component defines a component parameter called IncrementAmount that can be used to
specify the amount that the Counter should be incremented each time the button is clicked.

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
int currentCount = 0;

[Parameter]
public int IncrementAmount { get; set; } = 1;

void IncrementCount()
{
currentCount+=IncrementAmount;
}
}

To specify a component parameter in Blazor, use an attribute as you would in ASP.NET Web Forms:

<Counter IncrementAmount="10" />

Event handlers
Both ASP.NET Web Forms and Blazor provide an event-based programming model for handling UI events.
Examples of such events include button clicks and text input. In ASP.NET Web Forms, you use HTML server
controls to handle UI events exposed by the DOM, or you can handle events exposed by web server controls. The
events are surfaced on the server through form post-back requests. Consider the following Web Forms button
click example:
Counter.ascx

<asp:Button ID="ClickMeButton" runat="server" Text="Click me!" OnClick="ClickMeButton_Click" />

Counter.ascx.cs

public partial class Counter : System.Web.UI.UserControl

{
protected void ClickMeButton_Click(object sender, EventArgs e)
{
Console.WriteLine("The button was clicked!");
}
}

In Blazor, you can register handlers for DOM UI events directly using directive attributes of the form @on{event} .
The {event} placeholder represents the name of the event. For example, you can listen for button clicks like this:
<button @onclick="OnClick">Click me!</button>

@code {
void OnClick()
{
Console.WriteLine("The button was clicked!);
}
}

Event handlers can accept an optional, event-specific argument to provide more information about the event. For
example, mouse events can take a MouseEventArgs argument, but it isn't required.

<button @onclick="OnClick">Click me!</button>

@code {
void OnClick(MouseEventArgs e)
{
Console.WriteLine($"Mouse clicked at {e.ScreenX}, {e.ScreenY}.");
}
}

Instead of referring to a method group for an event handler, you can use a lambda expression. A lambda
expression allows you to close over other in-scope values.

@foreach (var buttonLabel in buttonLabels)

{
<button @onclick="() => Console.WriteLine($"The {buttonLabel} button was clicked!")">@buttonLabel</button>
}

Event handlers can execute synchronously or asynchronously. For example, the following OnClick event handler
executes asynchronously:

<button @onclick="OnClick">Click me!</button>

@code {
async Task OnClick()
{
var result = await Http.GetAsync("api/values");
}
}

After an event is handled, the component is rendered to account for any component state changes. With
asynchronous event handlers, the component is rendered immediately after the handler execution completes. The
component is rendered again after the asynchronous Task completes. This asynchronous execution mode
provides an opportunity to render some appropriate UI while the asynchronous Task is still in progress.
<button @onclick="Get message">Get message</button>

@if (showMessage)
{
@if (message == null)
{
<p><em>Loading...</em></p>
}
else
{
<p>The message is: @message</p>
}
}

@code
{
bool showMessage = false;
string message;

public async Task ShowMessage()

{
showMessage = true;
message = await MessageService.GetMessageAsync();
}
}

Components can also define their own events by defining a component parameter of type EventCallback<TValue> .
Event callbacks support all the variations of DOM UI event handlers: optional arguments, synchronous or
asynchronous, method groups, or lambda expressions.

<button class="btn btn-primary" @onclick="OnClick">Click me!</button>

@code {
[Parameter]
public EventCallback<MouseEventArgs> OnClick { get; set; }
}

Data binding
Blazor provides a simple mechanism to bind data from a UI component to the component's state. This approach
differs from the features in ASP.NET Web Forms for binding data from data sources to UI controls. We'll cover
handling data from different data sources in the Dealing with data section.
To create a two-way data binding from a UI component to the component's state, use the @bind directive
attribute. In the following example, the value of the check box is bound to the isChecked field.

<input type="checkbox" @bind="isChecked" />

@code {
bool isChecked;
}

When the component is rendered, the value of the checkbox is set to the value of the isChecked field. When the
user toggles the checkbox, the onchange event is fired and the isChecked field is set to the new value. The @bind
syntax in this case is equivalent to the following markup:

<input value="@isChecked" @onchange="(UIChangeEventArgs e) => isChecked = e.Value" />

To change the event used for the bind, use the @bind:event attribute.

<input @bind="text" @bind:event="oninput" />

@code {
string text;
}

Components can also support data binding to their parameters. To data bind, define an event callback parameter
with the same name as the bindable parameter. The "Changed" suffix is added to the name.
PasswordBox.razor

Password: <input
value="@Password"
@oninput="OnPasswordChanged"
type="@(showPassword ? "text" : "password")" />

<label><input type="checkbox" @bind="showPassword" />Show password</label>

@code {
private bool showPassword;

[Parameter]
public string Password { get; set; }

[Parameter]
public EventCallback<string> PasswordChanged { get; set; }

private Task OnPasswordChanged(ChangeEventArgs e)

{
Password = e.Value.ToString();
return PasswordChanged.InvokeAsync(Password);
}
}

To chain a data binding to an underlying UI element, set the value and handle the event directly on the UI element
instead of using the @bind attribute.
To bind to a component parameter, use a @bind-{Parameter} attribute to specify the parameter to which you want
to bind.

<PasswordBox @bind-Password="password" />

@code {
string password;
}

State changes
If the component's state has changed outside of a normal UI event or event callback, then the component must
manually signal that it needs to be rendered again. To signal that a component's state has changed, call the
StateHasChanged method on the component.

In the example below, a component displays a message from an AppState service that can be updated by other
parts of the app. The component registers its StateHasChanged method with the AppState.OnChange event so that
the component is rendered whenever the message gets updated.
public class AppState
{
public string Message { get; }

// Lets components receive change notifications

public event Action OnChange;

public void UpdateMessage(string message)

{
shortlist.Add(itinerary);
NotifyStateChanged();
}

private void NotifyStateChanged() => OnChange?.Invoke();

}

@inject AppState AppState

<p>App message: @AppState.Message</p>

@code {
protected override void OnInitialized()
{
AppState.OnChange += StateHasChanged
}
}

Component lifecycle
The ASP.NET Web Forms framework has well-defined lifecycle methods for modules, pages, and controls. For
example, the following control implements event handlers for the Init , Load , and UnLoad lifecycle events:
Counter.ascx.cs

public partial class Counter : System.Web.UI.UserControl

{
protected void Page_Init(object sender, EventArgs e) { ... }
protected void Page_Load(object sender, EventArgs e) { ... }
protected void Page_UnLoad(object sender, EventArgs e) { ... }
}

Blazor components also have a well-defined lifecycle. A component's lifecycle can be used to initialize component
state and implement advanced component behaviors.
All of Blazor's component lifecycle methods have both synchronous and asynchronous versions. Component
rendering is synchronous. You can't run asynchronous logic as part of the component rendering. All asynchronous
logic must execute as part of an async lifecycle method.
OnInitialized
The OnInitialized and OnInitializedAsync methods are used to initialize the component. A component is
typically initialized after it's first rendered. After a component is initialized, it may be rendered multiple times
before it's eventually disposed. The OnInitialized method is similar to the Page_Load event in ASP.NET Web
Forms pages and controls.

protected override void OnInitialized() { ... }

protected override async Task OnInitializedAsync() { await ... }
OnParametersSet
The OnParametersSet and OnParametersSetAsync methods are called when a component has received parameters
from its parent and the value are assigned to properties. These methods are executed after component
initialization and each time the component is rendered.

protected override void OnParametersSet() { ... }

protected override async Task OnParametersSetAsync() { await ... }

OnAfterRender
The OnAfterRender and OnAfterRenderAsync methods are called after a component has finished rendering.
Element and component references are populated at this point (more on these concepts below ). Interactivity with
the browser is enabled at this point. Interactions with the DOM and JavaScript execution can safely take place.

protected override void OnAfterRender(bool firstRender)

{
if (firstRender)
{
...
}
}
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
await ...
}
}

OnAfterRender and OnAfterRenderAsync aren't called when prerendering on the server.

The firstRender parameter is true the first time the component is rendered; otherwise, its value is false .
IDisposable
Blazor components can implement IDisposable to dispose of resources when the component is removed from
the UI. A Razor component can implement IDispose by using the @implements directive:

@using System
@implements IDisposable

...

@code {
public void Dispose()
{
...
}
}

Capture component references

In ASP.NET Web Forms, it's common to manipulate a control instance directly in code by referring to its ID. In
Blazor, it's also possible to capture and manipulate a reference to a component, although it's much less common.
To capture a component reference in Blazor, use the @ref directive attribute. The value of the attribute should
match the name of a settable field with the same type as the referenced component.
<MyLoginDialog @ref="loginDialog" ... />

@code {
MyLoginDialog loginDialog;

void OnSomething()
{
loginDialog.Show();
}
}

When the parent component is rendered, the field is populated with the child component instance. You can then
call methods on, or otherwise manipulate, the component instance.
Manipulating component state directly using component references isn't recommended. Doing so prevents the
component from being rendered automatically at the correct times.

Capture element references

Blazor components can capture references to an element. Unlike HTML server controls in ASP.NET Web Forms,
you can't manipulate the DOM directly using an element reference in Blazor. Blazor handles most DOM
interactions for you using its DOM diffing algorithm. Captured element references in Blazor are opaque. However,
they're used to pass a specific element reference in a JavaScript interop call. For more information about
JavaScript interop, see ASP.NET Core Blazor JavaScript interop.

Templated components
In ASP.NET Web Forms, you can create templated controls. Templated controls enable the developer to specify a
portion of the HTML used to render a container control. The mechanics of building templated server controls are
complex, but they enable powerful scenarios for rendering data in a user customizable way. Examples of templated
controls include Repeater and DataList .
Blazor components can also be templated by defining component parameters of type RenderFragment or
RenderFragment<T> . A RenderFragment represents a chunk of Razor markup that can then be rendered by the
component. A RenderFragment<T> is a chunk of Razor markup that takes a parameter that can be specified when
the render fragment is rendered.
Child content
Blazor components can capture their child content as a RenderFragment and render that content as part of the
component rendering. To capture child content, define a component parameter of type RenderFragment and name
it ChildContent .
ChildContentComponent.razor

<h1>Component with child content</h1>

<div>@ChildContent</div>

@code {
[Parameter]
public RenderFragment ChildContent { get; set; }
}

A parent component can then supply child content using normal Razor syntax.
<ChildContentComponent>
<p>The time is @DateTime.Now</p>
</ChildContentComponent>

Template parameters
A templated Blazor component can also define multiple component parameters of type RenderFragment or
RenderFragment<T> . The parameter for a RenderFragment<T> can be specified when it's invoked. To specify a generic
type parameter for a component, use the @typeparam Razor directive.
SimpleListView.razor

@typeparam TItem

@Heading

<ul>
@foreach (var item in Items)
{
<li>@ItemTemplate(item)</li>
}
</ul>

@code {
[Parameter]
public RenderFragment Heading { get; set; }

[Parameter]
public RenderFragment<TItem> ItemTemplate { get; set; }

[Parameter]
public IEnumerable<TItem> Items { get; set; }
}

When using a templated component, the template parameters can be specified using child elements that match
the names of the parameters. Component arguments of type RenderFragment<T> passed as elements have an
implicit parameter named context . You can change the name of this implement parameter using the Context
attribute on the child element. Any generic type parameters can be specified using an attribute that matches the
name of the type parameter. The type parameter will be inferred if possible:

<SimpleListView Items="messages" TItem="string">

<Heading>
<h1>My list</h1>
</Heading>
<ItemTemplate Content="message">
<p>The message is: @message</p>
</ItemTemplate>
</SimpleListView>

The output of this component looks like this:

<h1>My list</h1>
<ul>
<li>The message is: message1</li>
<li>The message is: message2</li>
<ul>

Code-behind
A Blazor component is typically authored in a single .razor file. However, it's also possible to separate the code and
markup using a code-behind file. To use a component file, add a C# file that matches the file name of the
component file but with a .cs extension added (Counter.razor.cs). Use the C# file to define a base class for the
component. You can name the base class anything you'd like, but it's common to name the class the same as the
component class, but with a Base extension added ( CounterBase ). The component-based class must also derive
from ComponentBase . Then, in the Razor component file, add the @inherits directive to specify the base class for
the component ( @inherits CounterBase ).
Counter.razor

@inherits CounterBase

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button @onclick="IncrementCount">Click me</button>

Counter.razor.cs

public class CounterBase : ComponentBase

{
protected int currentCount = 0;

protected void IncrementCount()

{
currentCount++;
}
}

The visibility of the component's members in the base class must be protected or public to be visible to the
component class.

Additional resources
The preceding isn't an exhaustive treatment of all aspects of Blazor components. For more information on how to
Create and use ASP.NET Core Razor components, see the Blazor documentation.

P R E V IO U S NEXT
Pages, routing, and layouts
9/23/2019 • 6 minutes to read • Edit Online

ASP.NET Web Forms apps are composed of pages defined in .aspx files. Each page's address is based on its
physical file path in the project. When a browser makes a request to the page, the contents of the page are
dynamically rendered on the server. The rendering accounts for both the page's HTML markup and its server
controls.
In Blazor, each page in the app is a component, typically defined in a .razor file, with one or more specified routes.
Routing mostly happens client-side without involving a specific server request. The browser first makes a request
to the root address of the app. A root Router component in the Blazor app then handles intercepting navigation
requests and them to the correct component.
Blazor also supports deep linking. Deep linking occurs when the browser makes a request to a specific route other
than the root of the app. Requests for deep links sent to the server are routed to the Blazor app, which then routes
the request client-side to the correct component.
A simple page in ASP.NET Web Forms might contain the following markup:
Name.aspx

<%@ Page Title="Name" Language="C#" MasterPageFile="~/Site.Master" AutoEventWireup="true"

CodeBehind="Name.aspx.cs" Inherits="WebApplication1.Name" %>

<asp:Content ID="BodyContent" ContentPlaceHolderID="MainContent" runat="server">

Name.aspx.cs

public partial class Name : System.Web.UI.Page

{
protected void Button1_Click1(object sender, EventArgs e)
{
Literal1.Text = "Hello " + TextBox1.Text;
}
}

The equivalent page in a Blazor app would look like this:

Name.razor

@page "/Name"
@layout MainLayout

<div>
What is your name?<br />
<input @bind="text" />
<button @onclick="OnClick">Submit</button>
</div>
<div>
if (name != null)
{
Hello @name
}
</div>

@code {
string text;
string name;

void OnClick() {
name = text;
}
}

Create pages
To create a page in Blazor, create a component and add the @page Razor directive to specify the route for the
component. The @page directive takes a single parameter, which is the route template to add to that component.

@page "/counter"

The route template parameter is required. Unlike ASP.NET Web Forms, the route to a Blazor component isn't
inferred from its file location (although that may be a feature added in the future).
The route template syntax is the same basic syntax used for routing in ASP.NET Web Forms. Route parameters
are specified in the template using braces. Blazor will bind route values to component parameters with the same
name (case-insensitive).

@page "/product/{id}"

<h1>Product @Id</h1>

@code {
[Parameter]
public string Id { get; set; }
}

You can also specify constraints on the value of the route parameter. For example, to constrain the product ID to
be an int :
@page "/product/{id:int}"

<h1>Product @Id</h1>

@code {
[Parameter]
public int Id { get; set; }
}

For a full list of the route constraints supported by Blazor, see Route constraints.

Router component
Routing in Blazor is handled by the Router component. The Router component is typically used in the app's root
component (App.razor).

<Router AppAssembly="@typeof(Program).Assembly">
<Found Context="routeData">
<RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
</Found>
<NotFound>
<LayoutView Layout="@typeof(MainLayout)">
<p>Sorry, there's nothing at this address.</p>
</LayoutView>
</NotFound>
</Router>

The Router component discovers the routable components in the specified AppAssembly and in the optionally
specified AdditionalAssemblies . When the browser navigates, the Router intercepts the navigation and renders
the contents of its Found parameter with the extracted RouteData if a route matches the address, otherwise the
Router renders its NotFound parameter.

The RouteView component handles rendering the matched component specified by the RouteData with its layout
if it has one. If the matched component doesn't have a layout, then the optionally specified DefaultLayout is used.
The LayoutView component renders its child content within the specified layout. We'll look at layouts more in
detail later in this chapter.

Navigation
In ASP.NET Web Forms, you trigger navigation to a different page by returning a redirect response to the
browser. For example:

protected void NavigateButton_Click(object sender, EventArgs e)

{
Response.Redirect("Counter");
}

Returning a redirect response isn't typically possible in Blazor. Blazor doesn't use a request-reply model. You can,
however, trigger browser navigations directly, as you can with JavaScript.
Blazor provides a NavigationManager service that can be used to:
Get the current browser address
Get the base address
Trigger navigations
Get notified when the address changes
To navigate to a different address, use the NavigateTo method:

@page "/"
@inject NavigationManager NavigationManager

<button @onclick="Navigate">Navigate</button>

@code {
void Navigate() {
NavigationManager.NavigateTo("counter");
}
}

For a description of all NavigationManager members, see URI and navigation state helpers.

Base URLs
If your Blazor app is deployed under a base path, then you need to specify the base URL in the page metadata
using the <base> tag for routing to work property. If the host page for the app is server-rendered using Razor,
then you can use the ~/ syntax to specify the app's base address. If the host page is static HTML, then you need
to specify the base URL explicitly.

<base href="~/" />

Page layout
Page layout in ASP.NET Web Forms is handled by Master Pages. Master Pages define a template with one or
more content placeholders that can then be supplied by individual pages. Master Pages are defined in .master files
and start with the <%@ Master %> directive. The content of the .master files is coded as you would an .aspx page,
but with the addition of <asp:ContentPlaceHolder> controls to mark where pages can supply content.
Site.master
<%@ Master Language="C#" AutoEventWireup="true" CodeBehind="Site.master.cs"
Inherits="WebApplication1.SiteMaster" %>

<!DOCTYPE html>
<html lang="en">
<head runat="server">
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title><%: Page.Title %> - My ASP.NET Application</title>
<link href="~/favicon.ico" rel="shortcut icon" type="image/x-icon" />
</head>
<body>
<form runat="server">
<div class="container body-content">
<asp:ContentPlaceHolder ID="MainContent" runat="server">
</asp:ContentPlaceHolder>
<hr />
<footer>
<p>© <%: DateTime.Now.Year %> - My ASP.NET Application</p>
</footer>
</div>
</form>
</body>
</html>

In Blazor, you handle page layout using layout components. Layout components inherit from
LayoutComponentBase , which defines a single Body property of type RenderFragment , which can be used to render
the contents of the page.
MainLayout.razor

@inherits LayoutComponentBase
<h1>Main layout</h1>
<div>
@Body
</div>

When the page with a layout is rendered, the page is rendered within the contents of the specified layout at the
location where the layout renders its Body property.
To apply a layout to a page, use the @layout directive:

@layout MainLayout

You can specify the layout for all components in a folder and subfolders using an _Imports.razor file. You can also
specify a default layout for all your pages using the Router component.
Master Pages can define multiple content placeholders, but layouts in Blazor only have a single Body property.
This limitation of Blazor layout components will hopefully be addressed in a future release.
Master Pages in ASP.NET Web Forms can be nested. That is, a Master Page may also use a Master Page. Layout
components in Blazor may be nested too. You can apply a layout component to a layout component. The contents
of the inner layout will be rendered within the outer layout.
ChildLayout.razor
@layout MainLayout
<h2>Child layout</h2>
<div>
@Body
</div>

Index.razor

@page "/"
@layout ChildLayout
<p>I'm in a nested layout!</p>

The rendered output for the page would then be:

<h1>Main layout</h1>
<div>
<h2>Child layout</h2>
<div>
<p>I'm in a nested layout!</p>
</div>
</div>

Layouts in Blazor don't typically define the root HTML elements for a page ( <html> , <body> , <head> , and so on).
The root HTML elements are instead defined in a Blazor app's host page, which is used to render the initial HTML
content for the app (see Bootstrap Blazor). The host page can render multiple root components for the app with
surrounding markup.
Components in Blazor, including pages, can't render <script> tags. This rendering restriction exists because
<script> tags get loaded once and then can't be changed. Unexpected behavior may occur if you try to render
the tags dynamically using Razor syntax. Instead, all <script> tags should be added to the app's host page.

P R E V IO U S NEXT
State management
9/23/2019 • 2 minutes to read • Edit Online

This content is coming soon.

P R E V IO U S NEXT
Forms and validation
9/24/2019 • 3 minutes to read • Edit Online

The ASP.NET Web Forms framework includes a set of validation server controls that handle validating user input
entered into a form ( RequiredFieldValidator , CompareValidator , RangeValidator , and so on). The ASP.NET Web
Forms framework also supports model binding and validating the model based on data annotations ( [Required] ,
[StringLength] , [Range] , and so on). The validation logic can be enforced both on the server and on the client
using unobtrusive JavaScript-based validation. The ValidationSummary server control is used to display a
summary of the validation errors to the user.
Blazor supports the sharing of validation logic between both the client and the server. ASP.NET provides pre-built
JavaScript implementations of many common server validations. In many cases, the developer still has to write
JavaScript to fully implement their app-specific validation logic. The same model types, data annotations, and
validation logic can be used on both the server and client.
Blazor provides a set of input components. The input components handle binding field data to a model and
validating the user input when the form is submitted.

INPUT COMPONENT RENDERED HTML ELEMENT

InputCheckbox <input type="checkbox">

InputDate <input type="date">

InputNumber <input type="number">

InputSelect <select>

InputText <input>

InputTextArea <textarea>

The EditForm component wraps these input components and orchestrates the validation process through an
EditContext . When creating an EditForm , you specify what model instance to bind to using the Model parameter.
Validation is typically done using data annotations, and it's extensible. To enable data annotation-based validation,
add the DataAnnotationsValidator component as a child of the EditForm . The EditForm component provides a
convenient event for handling valid ( OnValidSubmit ) and invalid ( OnInvalidSubmit ) submissions. There's also a
more generic OnSubmit event that lets you trigger and handle the validation yourself.
To display a validation error summary, use the ValidationSummary component. To display validation messages for a
specific input field, use the ValidationMessage component, specifying a lambda expression for the For parameter
that points to the appropriate model member.
The following model type defines several validation rules using data annotations:

using System;
using System.ComponentModel.DataAnnotations;

public class Starship

{
[Required]
[StringLength(16,
ErrorMessage = "Identifier too long (16 character limit).")]
public string Identifier { get; set; }

public string Description { get; set; }

[Required]
public string Classification { get; set; }

[Range(1, 100000,
ErrorMessage = "Accommodation invalid (1-100000).")]
public int MaximumAccommodation { get; set; }

[Required]
[Range(typeof(bool), "true", "true",
ErrorMessage = "This form disallows unapproved ships.")]
public bool IsValidatedDesign { get; set; }

[Required]
public DateTime ProductionDate { get; set; }
}

The following component demonstrates building a form in Blazor based on the Starship model type:
<h1>New Ship Entry Form</h1>

<EditForm Model="@starship" OnValidSubmit="@HandleValidSubmit">

<p>
<label for="identifier">Identifier: </label>
<InputText id="identifier" @bind-Value="starship.Identifier" />
<ValidationMessage For="() => starship.Identifier" />
</p>
<p>
<label for="description">Description (optional): </label>
<InputTextArea id="description" @bind-Value="starship.Description" />
</p>
<p>
<label for="classification">Primary Classification: </label>
<InputSelect id="classification" @bind-Value="starship.Classification">
<option value="">Select classification ...</option>
<option value="Exploration">Exploration</option>
<option value="Diplomacy">Diplomacy</option>
<option value="Defense">Defense</option>
</InputSelect>
<ValidationMessage For="() => starship.Classification" />
</p>
<p>
<label for="accommodation">Maximum Accommodation: </label>
<InputNumber id="accommodation" @bind-Value="starship.MaximumAccommodation" />
<ValidationMessage For="() => starship.MaximumAccommodation" />
</p>
<p>
<label for="valid">Engineering Approval: </label>
<InputCheckbox id="valid" @bind-Value="starship.IsValidatedDesign" />
<ValidationMessage For="() => starship.IsValidatedDesign" />
</p>
<p>
<label for="productionDate">Production Date: </label>
<InputDate id="productionDate" @bind-Value="starship.ProductionDate" />
<ValidationMessage For="() => starship.ProductionDate" />
</p>

<button type="submit">Submit</button>
</EditForm>

@code {
private Starship starship = new Starship();

private void HandleValidSubmit()

{
// Save the data
}
}

After the form submission, the model-bound data hasn't been saved to any data store, like a database. In a Blazor
WebAssembly app, the data must be sent to the server. For example, using an HTTP POST request. In a Blazor
Server app, the data is already on the server, but it must be persisted. Handling data access in Blazor apps is the
subject of the Dealing with data section.

Additional resources
For more information on forms and validation in Blazor apps, see the Blazor documentation.
P R E V IO U S NEXT
Data access and management
9/23/2019 • 2 minutes to read • Edit Online

This content is coming soon.

P R E V IO U S NEXT
Modules, handlers, and middleware
9/23/2019 • 2 minutes to read • Edit Online

This content is coming soon.

P R E V IO U S NEXT
App configuration
9/23/2019 • 2 minutes to read • Edit Online

This content is coming soon.

P R E V IO U S NEXT
Security: authentication and authorization in ASP.NET
Web Forms and Blazor
9/23/2019 • 2 minutes to read • Edit Online

This content is coming soon.

P R E V IO U S NEXT
Migrate from ASP.NET Web Forms to Blazor
9/23/2019 • 16 minutes to read • Edit Online

Migrating a code base from ASP.NET Web Forms to Blazor is a time-consuming task that requires planning. This
chapter outlines the process. Something that can ease the transition is to ensure the app adheres to an N -tier
architecture, wherein the app model (in this case, Web Forms) is separate from the business logic. This logical
separation of layers makes it clear what needs to move to .NET Core and Blazor.
For this example, the eShop app available on GitHub is used. eShop is a catalog service that provides CRUD
capabilities via form entry and validation.
Why should a working app be migrated to Blazor? Many times, there's no need. ASP.NET Web Forms will continue
to be supported for many years. However, many of the features that Blazor provides are only supported on a
migrated app. Such features include:
Performance improvements in the framework such as Span<T>
Ability to run as WebAssembly
Cross-platform support for Linux and macOS
App-local deployment or shared framework deployment without impacting other apps
If these or other new features are compelling enough, there may be value in migrating the app. The migration can
take different shapes; it can be the entire app, or only certain endpoints that require the changes. The decision to
migrate is ultimately based on the business problems to be solved by the developer.

Server-side versus client-side hosting

As described in the hosting models chapter, a Blazor app can be hosted in two different ways: server-side and
client-side. The server-side model uses ASP.NET Core SignalR connections to manage the DOM updates while
running any actual code on the server. The client-side model runs as WebAssembly within a browser and requires
no server connections. There are a number of differences that may affect which is best for a specific app:
Running as WebAssembly is still in development and may not support all features (such as threading) at the
current time
Chatty communication between the client and server may cause latency issues in server-side mode
Access to databases and internal or protected services require a separate service with client-side hosting
At the time of writing, the server-side model more closely resembles Web Forms. Most of this chapter focuses on
the server-side hosting model, as it's production-ready.

Create a new project

This initial migration step is to create a new project. This project type is based on the SDK style projects of .NET
Core and simplifies much of the boilerplate that was used in previous project formats. For more detail, please see
the chapter on Project Structure.
Once the project has been created, install the libraries that were used in the previous project. In older Web Forms
projects, you may have used the packages.config file to list the required NuGet packages. In the new SDK-style
project, packages.config has been replaced with <PackageReference> elements in the project file. A benefit to this
approach is that all dependencies are installed transitively. You only list the top-level dependencies you care about.
Many of the dependencies you're using are available for .NET Core, including Entity Framework 6 and log4net. If
there's no .NET Core or .NET Standard version available, the .NET Framework version can often be used. Your
mileage may vary. Any API used that isn't available in .NET Core causes a runtime error. Visual Studio notifies you
of such packages. A yellow icon appears on the project's References node in Solution Explorer.
In the Blazor-based eShop project, you can see the packages that are installed. Previously, the packages.config file
listed every package used in the project, resulting in a file almost 50 lines long. A snippet of packages.config is:

<?xml version="1.0" encoding="utf-8"?>

The <packages> element includes all necessary dependencies. It's difficult to identify which of these packages are
included because you require them. Some <package> elements are listed simply to satisfy the needs of
dependencies you require.
The Blazor project lists the dependencies you require within an <ItemGroup> element in the project file:

One NuGet package that simplifies the life of Web Forms developers is the Windows Compatibility Pack. Although
.NET Core is cross-platform, some features are only available on Windows. Windows-specific features are made
available by installing the compatibility pack. Examples of such features include the Registry, WMI, and Directory
Services. The package adds around 20,000 APIs and activates many services with which you may already be
familiar. The eShop project doesn't require the compatibility pack; but if your projects use Windows-specific
features, the package eases the migration efforts.

Enable startup process

The startup process for Blazor has changed from Web Forms and follows a similar setup for other ASP.NET Core
services. When hosted server-side, Blazor components are run as part of a normal ASP.NET Core app. When
hosted in the browser with WebAssembly, Blazor components use a similar hosting model. The difference is the
components are run as a separate service from any of the backend processes. Either way, the startup is similar.
The Global.asax.cs file is the default startup page for Web Forms projects. In the eShop project, this file configures
the Inversion of Control (IoC ) container and handles the various lifecycle events of the app or request. Some of
these events are handled with middleware (such as Application_BeginRequest ). Other events require the overriding
of specific services via dependency injection (DI).
By way of example, the Global.asax.cs file for eShop, contains the following code:
public class Global : HttpApplication, IContainerProviderAccessor
{
private static readonly ILog _log =
LogManager.GetLogger(System.Reflection.MethodBase.GetCurrentMethod().DeclaringType);

static IContainerProvider _containerProvider;

IContainer container;

public IContainerProvider ContainerProvider

{
get { return _containerProvider; }
}

protected void Application_Start(object sender, EventArgs e)

{
// Code that runs on app startup
RouteConfig.RegisterRoutes(RouteTable.Routes);
BundleConfig.RegisterBundles(BundleTable.Bundles);
ConfigureContainer();
ConfigDataBase();
}

/// <summary>
/// Track the machine name and the start time for the session inside the current session
/// </summary>
protected void Session_Start(Object sender, EventArgs e)
{
HttpContext.Current.Session["MachineName"] = Environment.MachineName;
HttpContext.Current.Session["SessionStartTime"] = DateTime.Now;
}

/// <summary>
/// http://docs.autofac.org/en/latest/integration/webforms.html
/// </summary>
private void ConfigureContainer()
{
var builder = new ContainerBuilder();
var mockData = bool.Parse(ConfigurationManager.AppSettings["UseMockData"]);
builder.RegisterModule(new ApplicationModule(mockData));
container = builder.Build();
_containerProvider = new ContainerProvider(container);
}

private void ConfigDataBase()

{
var mockData = bool.Parse(ConfigurationManager.AppSettings["UseMockData"]);

if (!mockData)
{
Database.SetInitializer<CatalogDBContext>(container.Resolve<CatalogDBInitializer>());
}
}

protected void Application_BeginRequest(object sender, EventArgs e)

{
//set the property to our new object
LogicalThreadContext.Properties["activityid"] = new ActivityIdHelper();

LogicalThreadContext.Properties["requestinfo"] = new WebRequestInfo();

_log.Debug("Application_BeginRequest");
}
}

The preceding file becomes the Startup class in server-side Blazor:

public class Startup
{
public Startup(IConfiguration configuration, IWebHostEnvironment env)
{
Configuration = configuration;
Env = env;
}

public IConfiguration Configuration { get; }

public IWebHostEnvironment Env { get; }

// This method gets called by the runtime. Use this method to add services to the container.
// For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?
LinkID=398940
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
services.AddServerSideBlazor();

if (Configuration.GetValue<bool>("UseMockData"))
{
services.AddSingleton<ICatalogService, CatalogServiceMock>();
}
else
{
services.AddScoped<ICatalogService, CatalogService>();
services.AddScoped<IDatabaseInitializer<CatalogDBContext>, CatalogDBInitializer>();
services.AddSingleton<CatalogItemHiLoGenerator>();
services.AddScoped(_ => new
CatalogDBContext(Configuration.GetConnectionString("CatalogDBContext")));
}
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
loggerFactory.AddLog4Net("log4Net.xml");

if (Env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
}

// Middleware for Application_BeginRequest

app.Use((ctx, next) =>
{
LogicalThreadContext.Properties["activityid"] = new ActivityIdHelper(ctx);
LogicalThreadContext.Properties["requestinfo"] = new WebRequestInfo(ctx);
return next();
});

app.UseStaticFiles();

app.UseRouting();

app.UseEndpoints(endpoints =>
{
endpoints.MapBlazorHub();
endpoints.MapFallbackToPage("/_Host");
});

ConfigDataBase(app);
}
private void ConfigDataBase(IApplicationBuilder app)
{
using (var scope = app.ApplicationServices.CreateScope())
{
var initializer = scope.ServiceProvider.GetService<IDatabaseInitializer<CatalogDBContext>>();

if (initializer != null)
{
Database.SetInitializer(initializer);
}
}
}
}

One significant change you may notice from Web Forms is the prominence of DI. DI has been a guiding principle
in the ASP.NET Core design. It supports customization of almost all aspects of the ASP.NET Core framework.
There's even a built-in service provider that can be used for many scenarios. If more customization is required, it
can be supported by the many community projects. For example, you can carry forward your third-party DI library
investment.
In the original eShop app, there's some configuration for session management. Since server-side Blazor uses
ASP.NET Core SignalR for communication, session state isn't supported as the connections may occur
independent of an HTTP context. An app that uses session state requires rearchitecting before running as a Blazor
app.
For more information about app startup, see App startup.

Migrate HTTP modules and handlers to middleware

HTTP modules and handlers are common patterns in Web Forms to control the HTTP request pipeline. Classes
that implement IHttpModule or IHttpHandler could be registered and process incoming requests. Web Forms
configures modules and handlers in the web.config file. Web Forms is also heavily based on app lifecycle event
handling. ASP.NET Core uses middleware instead. Middlewares are registered in the Configure method of the
Startup class. Middleware execution order is determined by the registration order.

In the Enable startup process section, a lifecycle event was raised by Web Forms as the Application_BeginRequest
method. This event isn't available in ASP.NET Core. One way to achieve this behavior is to implement middleware
as seen in the Startup.cs file example. This middleware does the same logic and then transfers control to the next
handler in the middleware pipeline.
For more information on migrating modules and handlers, see Migrate HTTP handlers and modules to ASP.NET
Core middleware.

Migrate static files

To serve static files (for example, HTML, CSS, images, and JavaScript), the files must be exposed by middleware.
Calling the UseStaticFiles method enables the serving of static files from the web root path. The default web root
directory is wwwroot, but it can be customized. As included in the Configure method of eShop's Startup class:

public void Configure(IApplicationBuilder app)

{
...

app.UseStaticFiles();

...
}
The eShop project enables basic static file access. There are many customizations available for static file access. For
information on enabling default files or a file browser, see Static files in ASP.NET Core.

Migrate runtime bundling and minification setup

Bundling and minification are performance optimization techniques for reducing the number and size of server
requests to retrieve certain file types. JavaScript and CSS often undergo some form of bundling or minification
before being sent to the client. In ASP.NET Web Forms, these optimizations are handled at runtime. The
optimization conventions are defined an App_Start/BundleConfig.cs file. In ASP.NET Core, a more declarative
approach is adopted. A file lists the files to be minified, along with specific minification settings.
For more information on bundling and minification, see Bundle and minify static assets in ASP.NET Core.

Migrate ASPX pages

A page in a Web Forms app is a file with the .aspx extension. A Web Forms page can often be mapped to a
component in Blazor. A Blazor component is authored in a file with the .razor extension. For the eShop project, five
pages are converted to a Razor page.
For example, the details view is comprised of three files in the Web Forms project: Details.aspx, Details.aspx.cs, and
Details.aspx.designer.cs. When converting to Blazor, the code-behind and markup are combined into Details.razor.
Razor compilation (equivalent to what's in .designer.cs files) is stored in the obj directory and aren't, by default,
viewable in Solution Explorer. The Web Forms page consists of the following markup:

<%@ Page Title="Details" Language="C#" MasterPageFile="~/Site.Master" AutoEventWireup="true"

CodeBehind="Details.aspx.cs" Inherits="eShopLegacyWebForms.Catalog.Details" %>

<asp:Content ID="Details" ContentPlaceHolderID="MainContent" runat="server">

<h2 class="esh-body-title">Details</h2>

<dt>Description
</dt>

<dt>Brand
</dt>

<dd>
<asp:Label runat="server" Text='<%#product.CatalogType.Type%>' />
</dd>
<dt>Price
<dt>Price
</dt>

<dt>Picture name
</dt>

<dt>Stock
</dt>

<dt>Restock
</dt>

<dt>Max stock
</dt>

</dl>
</div>

<div class="form-actions no-color esh-link-list">

<a runat="server" href='<%# GetRouteUrl("EditProductRoute", new {id =product.Id}) %>' class="esh-
link-item">Edit
</a>
|
<a runat="server" href="~" class="esh-link-item">Back to list
</a>
</div>

</div>
</asp:Content>

The preceding markup's code-behind includes the following code:

using eShopLegacyWebForms.Models;
using eShopLegacyWebForms.Services;
using log4net;
using System;
using System.Web.UI;

namespace eShopLegacyWebForms.Catalog
{
public partial class Details : System.Web.UI.Page
{
private static readonly ILog _log =
LogManager.GetLogger(System.Reflection.MethodBase.GetCurrentMethod().DeclaringType);

protected CatalogItem product;

public ICatalogService CatalogService { get; set; }

protected void Page_Load(object sender, EventArgs e)

{
var productId = Convert.ToInt32(Page.RouteData.Values["id"]);
_log.Info($"Now loading... /Catalog/Details.aspx?id={productId}");
product = CatalogService.FindCatalogItem(productId);

this.DataBind();
}
}
}

When converted to Blazor, the Web Forms page translates to the following code:

@page "/Catalog/Details/{id:int}"
@inject ICatalogService CatalogService
@inject ILogger<Details> Logger

<h2 class="esh-body-title">Details</h2>

<dl class="col-md-6 dl-horizontal">

<dt>
Description
</dt>

<dd>
@_item.Description
</dd>

<dt>
Brand
</dt>

<dd>
@_item.CatalogBrand.Brand
</dd>

<dd>
@_item.CatalogType.Type
</dd>
<dt>
Price
</dt>

<dd>
@_item.Price
</dd>

<dt>
Picture name
</dt>

<dd>
@_item.PictureFileName
</dd>

<dt>
Stock
</dt>

<dd>
@_item.AvailableStock
</dd>

<dt>
Restock
</dt>

<dd>
@_item.RestockThreshold
</dd>

<dt>
Max stock
</dt>

<dd>
@_item.MaxStockThreshold
</dd>

</dl>
</div>

</div>

@code {
private CatalogItem _item;

[Parameter]
public int Id { get; set; }

protected override void OnInitialized()

{
{
Logger.LogInformation("Now loading... /Catalog/Details/{Id}", Id);

_item = CatalogService.FindCatalogItem(Id);
}
}

Notice that the code and markup are in the same file. Any required services are made accessible with the @inject
attribute. Per the @page directive, this page can be accessed at the Catalog/Details/{id} route. The value of the
route's {id} placeholder has been constrained to an integer. As described in the routing section, unlike Web
Forms, a Razor component explicitly states its route and any parameters that are included. Many Web Forms
controls may not have exact counterparts in Blazor. There's often an equivalent HTML snippet that will serve the
same purpose. For example, the <asp:Label /> control can be replaced with an HTML <label> element.
Model validation in Blazor
If your Web Forms code includes validation, you can transfer much of what you have with little-to-no changes. A
benefit to running in Blazor is that the same validation logic can be run without needing custom JavaScript. Data
annotations enable easy model validation.
For example, the Create.aspx page has a data entry form with validation. An example snippet would look like this:

In Blazor, the equivalent markup is provided in a Create.razor file:

<EditForm Model="_item" OnValidSubmit="@...">

...
</EditForm>

The EditForm context includes validation support and can be wrapped around input. Data annotations are a
common way to add validation. Such validation support can be added via the DataAnnotationsValidator
component. For more information on this mechanism, see ASP.NET Core Blazor forms and validation.

Migrate built-in Web Forms controls

This content is coming soon.

Migrate configuration
In a Web Forms project, configuration data is most commonly stored in the web.config file. The configuration data
is accessed with ConfigurationManager . Services were often required to parse objects. With .NET Framework 4.7.2,
composability was added to configuration via ConfigurationBuilders . These builders allowed developers to add
various sources for configuration that was then composed at runtime to retrieve the necessary values.
ASP.NET Core introduced a flexible configuration system that allows you to define the configuration source or
sources used by your app and deployment. The ConfigurationBuilder infrastructure that you may be using in your
Web Forms app was modeled after the concepts used in the ASP.NET Core configuration system.
The following snippet demonstrates how the Web Forms eShop project uses web.config to store configuration
values:

It's common for secrets, such as database connection strings, to be stored within the web.config. The secrets are
inevitably persisted in unsecure locations, such as source control. With Blazor on ASP.NET Core, the preceding
XML -based configuration is replaced with the following JSON:

{
"ConnectionStrings": {
"CatalogDBContext": "Data Source=(localdb)\\MSSQLLocalDB; Initial
Catalog=Microsoft.eShopOnContainers.Services.CatalogDb; Integrated Security=True;
MultipleActiveResultSets=True;"
},
"UseMockData": true,
"UseCustomizationData": false
}

JSON is the default configuration format; however, ASP.NET Core supports many other formats, including XML.
There are also several community-supported formats.
The constructor in the Blazor project's Startup class accepts an IConfiguration instance through a DI technique
known as constructor injection:

public class Startup

{
public Startup(IConfiguration configuration, IWebHostEnvironment env)
{
Configuration = configuration;
Env = env;
}

...
}

By default, environment variables, JSON files (appsettings.json and appsettings.{Environment}.json), and

command-line options are registered as valid configuration sources in the configuration object. The configuration
sources can be accessed via Configuration[key] . A more advanced technique is to bind the configuration data to
objects using the options pattern. For more information on configuration and the options pattern, see
Configuration in ASP.NET Core and Options pattern in ASP.NET Core, respectively.

Migrate data access

Data access is an important aspect of any app. The eShop project stores catalog information in a database and
retrieves the data with Entity Framework (EF ) 6. Since EF 6 is supported in .NET Core 3.0, the project can continue
to use it.
The following EF -related changes were necessary to eShop:
In .NET Framework, the DbContext object accepts a string of the form name=ConnectionString and uses the
connection string from ConfigurationManager.AppSettings[ConnectionString] to connect. In .NET Core, this isn't
supported. The connection string must be supplied.
The database was accessed in a synchronous way. Though this works, scalability may suffer. This logic should be
moved to an asynchronous pattern.
Although there isn't the same native support for dataset binding, Blazor provides flexibility and power with its C#
support in a Razor page. For example, you can perform calculations and display the result. For more information
on data patterns in Blazor, see the Data access chapter.

Architectural changes
Finally, there are some important architectural differences to consider when migrating to Blazor. Many of these
changes are applicable to anything based on .NET Core or ASP.NET Core.
Because Blazor is built on .NET Core, there are considerations in ensuring support on .NET Core. Some of the
major changes include the removal of the following features:
Multiple AppDomains
Remoting
Code Access Security (CAS )
Security Transparency
For more information on techniques to identify necessary changes to support running on .NET Core, see Port your
code from .NET Framework to .NET Core.
ASP.NET Core is a reimagined version of ASP.NET and has some changes that may not initially seem obvious. The
main changes are:
No synchronization context, which means there's no HttpContext.Current , Thread.CurrentPrincipal , or other
static accessors
No shadow copying
No request queue
Many operations in ASP.NET Core are asynchronous, which allows easier off-loading of I/O -bound tasks. It's
important to never block by using Task.Wait() or Task.GetResult() , which can quickly exhaust thread pool
resources.

Migration conclusion
At this point, you've seen many examples of what it takes to move a Web Forms project to Blazor. For a full
example, see the eShopOnBlazor project.
P R E V IO U S

CSLA Blazor 02 28 PDF
100% (1)
CSLA Blazor 02 28 PDF
182 pages
Blazor For ASP NET Web Forms Developers PDF
No ratings yet
Blazor For ASP NET Web Forms Developers PDF
72 pages
Dockerizing Asp Net Core and Blazor Applications On Mac PDF
100% (1)
Dockerizing Asp Net Core and Blazor Applications On Mac PDF
64 pages
MV5
No ratings yet
MV5
730 pages
Traveling Blazor Webassembly: With Simple Food Recipe Page
No ratings yet
Traveling Blazor Webassembly: With Simple Food Recipe Page
24 pages
Blazor For ASP - Net Web Forms Developers
No ratings yet
Blazor For ASP - Net Web Forms Developers
84 pages
Blazor For ASP NET Web Forms Developers
No ratings yet
Blazor For ASP NET Web Forms Developers
99 pages
Blazor For ASP NET Web Forms Developers
No ratings yet
Blazor For ASP NET Web Forms Developers
95 pages
Blazor - A Beginners Guide
100% (1)
Blazor - A Beginners Guide
121 pages
Unleashing the Power of ASP.NET Core 7.0 and Angular 16 A Comprehensive Guide
From Everand
Unleashing the Power of ASP.NET Core 7.0 and Angular 16 A Comprehensive Guide
Pedro Martins
No ratings yet
Learning MVCPart 2 Creating MVC Application Amp Perform CRUD Operations Using LINQ To SQL
No ratings yet
Learning MVCPart 2 Creating MVC Application Amp Perform CRUD Operations Using LINQ To SQL
27 pages
MVC 5 Intro PDF
No ratings yet
MVC 5 Intro PDF
35 pages
Core A-Z
100% (1)
Core A-Z
325 pages
MVC Presentation
No ratings yet
MVC Presentation
20 pages
Creating Web API in ASP - Net Core 2.0 - CodeProject
No ratings yet
Creating Web API in ASP - Net Core 2.0 - CodeProject
36 pages
Absolutely Awesome Book On CSharp and .NET - Sample Chapters PDF
No ratings yet
Absolutely Awesome Book On CSharp and .NET - Sample Chapters PDF
96 pages
Introduction To Log4net
100% (1)
Introduction To Log4net
19 pages
Learning MVCPart 3 Creating MVC Application Amp Perform CRUD Operations Using EntityFramework
No ratings yet
Learning MVCPart 3 Creating MVC Application Amp Perform CRUD Operations Using EntityFramework
15 pages
Blazor Succinctly
No ratings yet
Blazor Succinctly
86 pages
51a6d104504b4f749940f2345eda1ca9
No ratings yet
51a6d104504b4f749940f2345eda1ca9
6,634 pages
Introduction To ASP - NET MVC 4
No ratings yet
Introduction To ASP - NET MVC 4
89 pages
Building An Enterprise Application With ASP Dot NET Core MVC
No ratings yet
Building An Enterprise Application With ASP Dot NET Core MVC
80 pages
Aspnet Core Aspnetcore 7.0
No ratings yet
Aspnet Core Aspnetcore 7.0
6,555 pages
Blazor Webassembly Succinctly
100% (1)
Blazor Webassembly Succinctly
111 pages
AspNet Core Documentation PDF
No ratings yet
AspNet Core Documentation PDF
3,087 pages
Developing Asp Net Core MVC Web Applications m20486 m20486 PDF
No ratings yet
Developing Asp Net Core MVC Web Applications m20486 m20486 PDF
6 pages
Integrating An ASP - Net MVC Web Application in Sitecore Cms-A4
No ratings yet
Integrating An ASP - Net MVC Web Application in Sitecore Cms-A4
26 pages
Core With Dapper and Vs 2017 Using JWT Authentication WEB API and Consume It in Angular2 Client Application - CodeProject
No ratings yet
Core With Dapper and Vs 2017 Using JWT Authentication WEB API and Consume It in Angular2 Client Application - CodeProject
11 pages
Web Api
No ratings yet
Web Api
27 pages
Resume of Yaseer ASP - Net MVC C# 7yr
No ratings yet
Resume of Yaseer ASP - Net MVC C# 7yr
10 pages
Index
No ratings yet
Index
90 pages
Top 50 Jquery Interview Questions
No ratings yet
Top 50 Jquery Interview Questions
7 pages
Jquery Fundamentals
No ratings yet
Jquery Fundamentals
20 pages
Building N-Layered Applications With ASP - NET 4.5 PDF
100% (2)
Building N-Layered Applications With ASP - NET 4.5 PDF
164 pages
C# Case Studies
No ratings yet
C# Case Studies
31 pages
MVC
No ratings yet
MVC
95 pages
Diving Into Microsoft Net Entity Framework
No ratings yet
Diving Into Microsoft Net Entity Framework
217 pages
Aspnet Core Conceptual
No ratings yet
Aspnet Core Conceptual
1,593 pages
C# Interview Questions
100% (1)
C# Interview Questions
7 pages
Core
No ratings yet
Core
12 pages
Latest Jquery Interview Questions & Answers
No ratings yet
Latest Jquery Interview Questions & Answers
18 pages
Push Service With ASP - NET SignalR
No ratings yet
Push Service With ASP - NET SignalR
57 pages
Microsoft Press CSharp Programmer's Cookbook
No ratings yet
Microsoft Press CSharp Programmer's Cookbook
11 pages
Learning MVCPart 1 Introduction To MVC Architecture and Separation of Concerns
No ratings yet
Learning MVCPart 1 Introduction To MVC Architecture and Separation of Concerns
3 pages
Core Web API PDF
No ratings yet
Core Web API PDF
107 pages
Software Architecture with C# 10 and .NET 6 - Third Edition Gabriel Baptista All Chapters Instant Download
100% (2)
Software Architecture with C# 10 and .NET 6 - Third Edition Gabriel Baptista All Chapters Instant Download
40 pages
Sitecore Powershell Extensions
100% (1)
Sitecore Powershell Extensions
463 pages
Building A Basic Sitecore Website
No ratings yet
Building A Basic Sitecore Website
21 pages
Reactive Programming With Reactjs PDF
No ratings yet
Reactive Programming With Reactjs PDF
69 pages
Web Component Development With Angularjs
No ratings yet
Web Component Development With Angularjs
264 pages
General ASP NET Questions - 16
100% (1)
General ASP NET Questions - 16
16 pages
Web Application Web Forms
100% (1)
Web Application Web Forms
66 pages
NUnit
0% (1)
NUnit
47 pages
Dot Net
No ratings yet
Dot Net
9 pages
SignalR Blueprints - Sample Chapter
No ratings yet
SignalR Blueprints - Sample Chapter
25 pages
JSF 2.0 Cookbook: LITE
From Everand
JSF 2.0 Cookbook: LITE
Anghel Leonard
No ratings yet
Top 10 Xamarin Tips and Traps
From Everand
Top 10 Xamarin Tips and Traps
Charles Pluta
No ratings yet
Ultimate AWS Certified Cloud Practitioner’s Exam Guide: Master the Concepts, Services, Security, and Architectural Best Practices of AWS, EC2, S3, and RDS, and Crack AWS CLF-C02 Certification (English Edition)
From Everand
Ultimate AWS Certified Cloud Practitioner’s Exam Guide: Master the Concepts, Services, Security, and Architectural Best Practices of AWS, EC2, S3, and RDS, and Crack AWS CLF-C02 Certification (English Edition)
Gaurav H Kankaria
No ratings yet
Mastering Vue.js: Building Modern Web Applications
From Everand
Mastering Vue.js: Building Modern Web Applications
Pedro Martins
No ratings yet
Backbone.js Patterns and Best Practices
From Everand
Backbone.js Patterns and Best Practices
Swarnendu De
No ratings yet
IDL Smart Printing Resource Kit Developer Guide PDF
No ratings yet
IDL Smart Printing Resource Kit Developer Guide PDF
28 pages
by Sarthak Gupta 1109031149 EC 4-c
No ratings yet
by Sarthak Gupta 1109031149 EC 4-c
23 pages
MCQ Bank-1
No ratings yet
MCQ Bank-1
119 pages
Top 10 Senior .NET Developer Interview Questions
No ratings yet
Top 10 Senior .NET Developer Interview Questions
23 pages
Mfd-Ubuntu University of Southampton
No ratings yet
Mfd-Ubuntu University of Southampton
5 pages
TDD
No ratings yet
TDD
34 pages
C# - If A Folder Does Not Exist, Create It - Stack Overflow
No ratings yet
C# - If A Folder Does Not Exist, Create It - Stack Overflow
11 pages
Introducing .NET MAUI: Build and Deploy Cross-platform Applications Using C# and .NET Multi-platform App UI 1st Edition Shaun Lawrence instant download
100% (4)
Introducing .NET MAUI: Build and Deploy Cross-platform Applications Using C# and .NET Multi-platform App UI 1st Edition Shaun Lawrence instant download
78 pages
Dotnet
No ratings yet
Dotnet
22 pages
Quick Guide PDF
No ratings yet
Quick Guide PDF
123 pages
DotnetConf2019HCMC NETCore3
No ratings yet
DotnetConf2019HCMC NETCore3
11 pages
Download Complete (Ebook) Beginning gRPC with ASP.NET Core 6: Build Applications using ASP.NET Core Razor Pages, Angular, and Best Practices in .NET 6 by Anthony Giretti ISBN 9781484280072, 1484280075 PDF for All Chapters
100% (6)
Download Complete (Ebook) Beginning gRPC with ASP.NET Core 6: Build Applications using ASP.NET Core Razor Pages, Angular, and Best Practices in .NET 6 by Anthony Giretti ISBN 9781484280072, 1484280075 PDF for All Chapters
81 pages
CSharp MidTerm
No ratings yet
CSharp MidTerm
74 pages
Dotnet Framework
No ratings yet
Dotnet Framework
60 pages
DNCMag Issue38
No ratings yet
DNCMag Issue38
123 pages
NET Framework
No ratings yet
NET Framework
30 pages
Instant ebooks textbook Introducing .NET 6 - Getting Started with Blazor, MAUI, Windows App SDK, Desktop Development, and Containers Nico Vermeir download all chapters
100% (3)
Instant ebooks textbook Introducing .NET 6 - Getting Started with Blazor, MAUI, Windows App SDK, Desktop Development, and Containers Nico Vermeir download all chapters
40 pages
Android Interview Questions and Answers
No ratings yet
Android Interview Questions and Answers
3 pages
Augmented Reality PDF
100% (3)
Augmented Reality PDF
8 pages
Download Mobile Development with NET Build cross platform mobile applications with Xamarin Forms 5 and ASP NET Core 5 2nd Edition Can Bilgin ebook All Chapters PDF
100% (2)
Download Mobile Development with NET Build cross platform mobile applications with Xamarin Forms 5 and ASP NET Core 5 2nd Edition Can Bilgin ebook All Chapters PDF
51 pages
Output Log Rimworld
No ratings yet
Output Log Rimworld
212 pages
Blazor PDF
100% (1)
Blazor PDF
64 pages
Tutorial
0% (1)
Tutorial
122 pages
Net Core Interview Questions
No ratings yet
Net Core Interview Questions
23 pages
Mobile Game Security: Is IL2CPP So Secure?
No ratings yet
Mobile Game Security: Is IL2CPP So Secure?
22 pages
A History of The Unity Game Engine
100% (1)
A History of The Unity Game Engine
44 pages
Xperia Firmware Downloader
No ratings yet
Xperia Firmware Downloader
4 pages
Moving from Unity to Godot: An In-Depth Handbook to Godot for Unity Users Alan Thorn instant download
100% (5)
Moving from Unity to Godot: An In-Depth Handbook to Godot for Unity Users Alan Thorn instant download
64 pages
Qmodmanager log-SubnauticaZero
No ratings yet
Qmodmanager log-SubnauticaZero
6 pages
Introducing Net Maui Build and Deploy Cross Platform Applications Using c and Net Multi Platform App Ui 1nbsped 9781484292334 9781484292341
No ratings yet
Introducing Net Maui Build and Deploy Cross Platform Applications Using c and Net Multi Platform App Ui 1nbsped 9781484292334 9781484292341
484 pages