Blazor PDF
Blazor PDF
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:
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.
NEXT
An introduction to Blazor for ASP.NET Web Forms
developers
9/23/2019 • 8 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.
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
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
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.
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.
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
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.
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 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.
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.
P R E V IO U S NEXT
Project structure for Blazor apps
9/23/2019 • 8 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.
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:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp3.0</TargetFramework>
</PropertyGroup>
</Project>
The project file for a Blazor WebAssembly app looks slightly more involved (exact version numbers may vary):
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<RazorLangVersion>3.0</RazorLangVersion>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Blazor" Version="3.1.0" />
<PackageReference Include="Microsoft.AspNetCore.Blazor.Build" Version="3.1.0" PrivateAssets="all" />
<PackageReference Include="Microsoft.AspNetCore.Blazor.HttpClient" Version="3.1.0" />
<PackageReference Include="Microsoft.AspNetCore.Blazor.DevServer" Version="3.1.0" PrivateAssets="all" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\Shared\BlazorWebAssemblyApp1.Shared.csproj" />
</ItemGroup>
</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.
<ItemGroup>
<PackageReference Include="Newtonsoft.Json" Version="12.0.2" />
</ItemGroup>
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.
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
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>
<script src="_framework/blazor.server.js"></script>
</body>
</html>
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>
<script src="_framework/blazor.webassembly.js"></script>
</body>
</html>
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.
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.
P R E V IO U S NEXT
App startup
9/23/2019 • 2 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.
P R E V IO U S NEXT
Build reusable UI components with Blazor
10/8/2019 • 16 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.
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>
<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.
@page Specifies the route for the @page "/product/{id}" <%@ Page %>
component
DIRECTIVE DESCRIPTION EXAMPLE WEB FORMS EQUIVALENT
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.
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.
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:
<Counter />
@using MyComponentLib
<Counter />
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>
@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:
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
Counter.ascx.cs
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.
@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.
Event handlers can execute synchronously or asynchronously. For example, the following OnClick event handler
executes asynchronously:
@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;
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.
@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.
@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:
@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")" />
@code {
private bool showPassword;
[Parameter]
public string Password { get; set; }
[Parameter]
public EventCallback<string> PasswordChanged { get; set; }
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.
@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; }
@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
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.
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.
@using System
@implements IDisposable
...
@code {
public void Dispose()
{
...
}
}
@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.
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
<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:
<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>
Counter.razor.cs
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
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.
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
Name.aspx.cs
@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:
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.
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>
<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
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.
P R E V IO U S NEXT
Forms and validation
9/24/2019 • 3 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.
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.
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;
[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>
<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();
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
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.
P R E V IO U S NEXT
Modules, handlers, and middleware
9/23/2019 • 2 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.
P R E V IO U S NEXT
App configuration
9/23/2019 • 2 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.
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
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.
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
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.
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.
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:
<ItemGroup>
<PackageReference Include="Autofac" Version="4.9.3" />
<PackageReference Include="EntityFramework" Version="6.3.0-preview9-19423-04" />
<PackageReference Include="log4net" Version="2.0.8" />
</ItemGroup>
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.
/// <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);
}
if (!mockData)
{
Database.SetInitializer<CatalogDBContext>(container.Resolve<CatalogDBInitializer>());
}
}
_log.Debug("Application_BeginRequest");
}
}
// 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");
}
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.
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.
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.
<div class="container">
<div class="row">
<asp:Image runat="server" CssClass="col-md-6 esh-picture" ImageUrl='<%#"/Pics/" +
product.PictureFileName%>' />
<dl class="col-md-6 dl-horizontal">
<dt>Name
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.Name%>' />
</dd>
<dt>Description
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.Description%>' />
</dd>
<dt>Brand
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.CatalogBrand.Brand%>' />
</dd>
<dt>Type
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.CatalogType.Type%>' />
</dd>
<dt>Price
<dt>Price
</dt>
<dd>
<asp:Label CssClass="esh-price" runat="server" Text='<%#product.Price%>' />
</dd>
<dt>Picture name
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.PictureFileName%>' />
</dd>
<dt>Stock
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.AvailableStock%>' />
</dd>
<dt>Restock
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.RestockThreshold%>' />
</dd>
<dt>Max stock
</dt>
<dd>
<asp:Label runat="server" Text='<%#product.MaxStockThreshold%>' />
</dd>
</dl>
</div>
</div>
</asp:Content>
namespace eShopLegacyWebForms.Catalog
{
public partial class Details : System.Web.UI.Page
{
private static readonly ILog _log =
LogManager.GetLogger(System.Reflection.MethodBase.GetCurrentMethod().DeclaringType);
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>
<div class="container">
<div class="row">
<img class="col-md-6 esh-picture" src="@($"/Pics/{_item.PictureFileName}")">
<dd>
@_item.Name
</dd>
<dt>
Description
</dt>
<dd>
@_item.Description
</dd>
<dt>
Brand
</dt>
<dd>
@_item.CatalogBrand.Brand
</dd>
<dt>
Type
</dt>
<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; }
_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:
<div class="form-group">
<label class="control-label col-md-2">Name</label>
<div class="col-md-3">
<asp:TextBox ID="Name" runat="server" CssClass="form-control"></asp:TextBox>
<asp:RequiredFieldValidator runat="server" ControlToValidate="Name" Display="Dynamic"
CssClass="field-validation-valid text-danger" ErrorMessage="The Name field is required." />
</div>
</div>
<div class="form-group">
<label class="control-label col-md-2">Name</label>
<div class="col-md-3">
<InputText class="form-control" @bind-Value="_item.Name" />
<ValidationMessage For="(() => _item.Name)" />
</div>
</div>
...
</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 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:
<configuration>
<configSections>
<section name="entityFramework" type="System.Data.Entity.Internal.ConfigFile.EntityFrameworkSection,
EntityFramework, Version=6.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false"
/>
</configSections>
<connectionStrings>
<add name="CatalogDBContext" connectionString="Data Source=(localdb)\MSSQLLocalDB; Initial
Catalog=Microsoft.eShopOnContainers.Services.CatalogDb; Integrated Security=True;
MultipleActiveResultSets=True;" providerName="System.Data.SqlClient" />
</connectionStrings>
<appSettings>
<add key="UseMockData" value="true" />
<add key="UseCustomizationData" value="false" />
</appSettings>
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:
...
}
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