Migrate Web Forms data access and application architecture to Blazor Server. Covers EF6 to EF Core, Session state to scoped services, Global.asax to Program.cs, Web.config to appsettings.json, and HTTP handlers to middleware. WHEN: "migrate EF6", "session state to services", "Global.asax to Program.cs", "Web.config to appsettings", "data access migration".
This skill covers migrating Web Forms data access patterns and application architecture to Blazor Server. These are the Layer 3 architecture decisions that require project-specific judgment.
Related skills:
/bwfc-migration — Core markup migration (controls, expressions, layouts)/bwfc-identity-migration — Authentication and authorization migrationUse this skill when you need to:
SelectMethod string to SelectHandler delegate, replace DataSource controls with service injectionSession/ViewState/Application state to Blazor patternsGlobal.asax to Program.csWeb.config to appsettings.jsonPages inheriting WebFormsPageBase get a Session property backed by SessionShim.
SessionShim works in BOTH SSR and interactive modes:
ISession (cookie-backed)ConcurrentDictionary scoped per circuitOriginal Web Forms:
Session["CartId"] = Guid.NewGuid().ToString();
var cartId = Session["CartId"].ToString();
Session["payment_amt"] = 99.99m;
Migrated Blazor (IDENTICAL):
Session["CartId"] = Guid.NewGuid().ToString();
var cartId = Session["CartId"].ToString();
Session["payment_amt"] = 99.99m;
No IHttpContextAccessor. No Minimal API. No cookies. Just Session["key"].
For non-page components, inject SessionShim directly:
@inject SessionShim Session
@code {
protected override void OnInitialized()
{
var userId = Session["UserId"]?.ToString() ?? "guest";
}
}
Only consider alternatives when you need cross-tab or cross-server persistence:
ProtectedBrowserStorage — For data that must survive page refreshes:
@inject ProtectedSessionStorage SessionStorage
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
var result = await SessionStorage.GetAsync<ShoppingCart>("cart");
cart = result.Success ? result.Value! : new ShoppingCart();
}
}
Database-backed — For shopping carts that persist across sessions:
public class CartService(IDbContextFactory<AppDbContext> factory)
{
public async Task<Cart> GetCartAsync(string userId)
{
using var db = factory.CreateDbContext();
return await db.Carts
.Include(c => c.Items)
.FirstOrDefaultAsync(c => c.UserId == userId) ?? new Cart();
}
}
Scoped services — When the pattern doesn't fit key-value storage:
public class WizardStateService
{
public int CurrentStep { get; set; }
public FormData Data { get; set; } = new();
public bool IsComplete => CurrentStep == 5 && Data.IsValid();
}
// Program.cs
builder.Services.AddScoped<WizardStateService>();
Progression model:
Web Forms: EF6 with DbContext instantiated directly in code-behind or via SelectMethod string binding.
Blazor: EF Core 10.0.3 (latest .NET 10) with IDbContextFactory registered in DI.
Step 1: Detect the provider. The L1 script's
Find-DatabaseProviderfunction readsWeb.config<connectionStrings>and scaffolds the correct EF Core package. Check the L1 output's[DatabaseProvider]review item for the detected provider and connection string. Use these values in yourProgram.csconfiguration — do not guess or substitute.CRITICAL: Preserve the original database provider. Examine the Web Forms project's
Web.configconnection strings and EF configuration to identify the database provider (SQL Server, PostgreSQL, MySQL, SQLite, Oracle, etc.). The migrated Blazor application MUST use the same database provider — do NOT switch providers unless explicitly requested by the user.⚠️ NEVER default to SQLite. The most common Web Forms database is SQL Server (often LocalDB for dev). If you see
System.Data.SqlClientor(LocalDB)in connection strings, useMicrosoft.EntityFrameworkCore.SqlServer— NOTMicrosoft.EntityFrameworkCore.Sqlite. SQLite is ONLY appropriate if the original application specifically usedSystem.Data.SQLite.
Step 1: Identify the original provider from the Web Forms project:
| Web.config Indicator | Original Provider | EF Core Package |
|---|---|---|
providerName="System.Data.SqlClient" | SQL Server | Microsoft.EntityFrameworkCore.SqlServer |
providerName="System.Data.SQLite" | SQLite | Microsoft.EntityFrameworkCore.Sqlite |
providerName="Npgsql" or Server=...;Port=5432 | PostgreSQL | Npgsql.EntityFrameworkCore.PostgreSQL |
providerName="MySql.Data.MySqlClient" | MySQL | Pomelo.EntityFrameworkCore.MySql or MySql.EntityFrameworkCore |
providerName="Oracle.ManagedDataAccess.Client" | Oracle | Oracle.EntityFrameworkCore |
Step 2: Install the matching EF Core provider package in the Blazor project:
# Example for SQL Server
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 10.0.3
# Example for PostgreSQL
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL --version 10.0.3
# Example for MySQL (Pomelo)
dotnet add package Pomelo.EntityFrameworkCore.MySql --version 10.0.3
Step 3: Configure the matching provider in Program.cs:
// SQL Server — matches System.Data.SqlClient
options.UseSqlServer(connectionString)
// PostgreSQL — matches Npgsql
options.UseNpgsql(connectionString)
// MySQL — matches MySql.Data.MySqlClient
options.UseMySql(connectionString, ServerVersion.AutoDetect(connectionString))
// SQLite — matches System.Data.SQLite
options.UseSqlite(connectionString)
Install matching EF Core packages for .NET 10:
Microsoft.EntityFrameworkCore, the provider-specific package (see table above),.Tools, and.Design.
// Web Forms — direct DbContext in code-behind
public IQueryable<Product> GetProducts()
{
var db = new ProductContext();
return db.Products;
}
// Blazor — Program.cs (use the provider that matches the original Web Forms database)
builder.Services.AddDbContextFactory<ProductContext>(options =>
options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
// ↑ Replace with UseNpgsql(), UseMySql(), UseSqlite(), etc. to match original provider
// Blazor — Service layer
public class ProductService(IDbContextFactory<ProductContext> factory)
{
public async Task<List<Product>> GetProductsAsync()
{
using var db = factory.CreateDbContext();
return await db.Products.ToListAsync();
}
public async Task<Product?> GetProductAsync(int id)
{
using var db = factory.CreateDbContext();
return await db.Products.FindAsync(id);
}
}
Critical: Use
IDbContextFactory, NOTAddDbContext, for Blazor Server. Blazor circuits are long-lived — a singleDbContextaccumulates stale data and tracking issues.
| EF6 | EF Core | Notes |
|---|---|---|
using System.Data.Entity; | using Microsoft.EntityFrameworkCore; | Namespace change |
DbModelBuilder in OnModelCreating | ModelBuilder | Same concepts, different API |
HasRequired() / HasOptional() | Navigation properties + IsRequired() | Simpler relationship config |
Database.SetInitializer(...) | Database.EnsureCreated() or Migrations | Different init strategy |
db.Products.Include("Category") | db.Products.Include(p => p.Category) | Prefer lambda includes |
WillCascadeOnDelete(false) | .OnDelete(DeleteBehavior.Restrict) | Cascade config |
.HasDatabaseGeneratedOption(...) | .ValueGeneratedOnAdd() | Key generation |
<!-- Web Forms — Web.config -->
<connectionStrings>
<add name="DefaultConnection"
connectionString="Data Source=(LocalDb)\MSSQLLocalDB;Initial Catalog=MyApp;Integrated Security=True"
providerName="System.Data.SqlClient" />
</connectionStrings>
// Blazor — appsettings.json
{
"ConnectionStrings": {
"DefaultConnection": "Data Source=(LocalDb)\\MSSQLLocalDB;Initial Catalog=MyApp;Integrated Security=True"
}
}
Web Forms DataSource controls have no BWFC equivalent. Replace with injected services.
<!-- Web Forms — declarative data binding -->
<asp:SqlDataSource ID="ProductsDS" runat="server"
ConnectionString="<%$ ConnectionStrings:DefaultConnection %>"
SelectCommand="SELECT * FROM Products" />
<asp:GridView DataSourceID="ProductsDS" runat="server" />
@* Blazor — service injection *@
@inject IProductService ProductService
<GridView Items="products" ItemType="Product" AutoGenerateColumns="true" />
@code {
private List<Product> products = new();
protected override async Task OnInitializedAsync()
{
products = await ProductService.GetProductsAsync();
}
}
// Program.cs — use the provider that matches the original Web Forms database
builder.Services.AddRazorComponents().AddInteractiveServerComponents();
builder.Services.AddBlazorWebFormsComponents(); // ⚠️ REQUIRED — registers BWFC services
builder.Services.AddDbContextFactory<ProductContext>(options =>
options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));
// ↑ Match the original provider: UseNpgsql(), UseMySql(), UseSqlite(), etc.
builder.Services.AddScoped<IProductService, ProductService>();
builder.Services.AddScoped<ICategoryService, CategoryService>();
builder.Services.AddScoped<IOrderService, OrderService>();
// ... after builder.Build() ...
app.UseBlazorWebFormsComponents(); // ⚠️ REQUIRED — .aspx URL rewriting middleware. BEFORE MapRazorComponents.
app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
BWFC's DataBoundComponent<ItemType> has a native SelectMethod parameter of type SelectHandler<ItemType> — a delegate with signature (int maxRows, int startRowIndex, string sortByExpression, out int totalRowCount) → IQueryable<ItemType>. When set, OnAfterRenderAsync automatically calls it to populate Items. This is the native BWFC data-binding pattern that mirrors how Web Forms did it.
Option A — Preserve SelectMethod as delegate (recommended):
| Web Forms SelectMethod | BWFC SelectMethod Delegate |
|---|---|
SelectMethod="GetProducts" | SelectMethod="@productService.GetProducts" (if signature matches SelectHandler<T>) |
SelectMethod="GetProduct" | SelectMethod="@productService.GetProduct" (or use DataItem for single-record controls) |
Option B — Items binding (ONLY when original used DataSource, NOT SelectMethod):
⚠️ Use Option B ONLY when the original Web Forms markup used
DataSource/DataBind(), NOT when it usedSelectMethod. If the original hadSelectMethod="GetProducts", you MUST use Option A above.
| Web Forms SelectMethod | Blazor Service Call |
|---|---|
SelectMethod="GetProducts" | products = await ProductService.GetProductsAsync(); then Items="@products" |
SelectMethod="GetProduct" | product = await ProductService.GetProductAsync(id); then DataItem="@product" |
CRUD methods (no BWFC parameter equivalent — wire to service calls in event handlers):
| Web Forms Method | Blazor Service Call |
|---|---|
InsertMethod="InsertProduct" | await ProductService.InsertAsync(product); |
UpdateMethod="UpdateProduct" | await ProductService.UpdateAsync(product); |
DeleteMethod="DeleteProduct" | await ProductService.DeleteAsync(id); |
Web Forms: Session["key"], ViewState["key"], Application["key"] dictionaries.
Blazor: SessionShim (auto-registered by AddBlazorWebFormsComponents()), component fields, and singleton services.
No code changes needed. WebFormsPageBase.Session delegates to SessionShim automatically:
// Web Forms — works IDENTICALLY in Blazor via SessionShim
Session["ShoppingCart"] = cart;
var cart = (ShoppingCart)Session["ShoppingCart"];
// SessionShim also supports typed access:
var cart = Session.Get<ShoppingCart>("ShoppingCart");
Session.Set("ShoppingCart", cart);
How SessionShim works:
ISession (cookie-persisted)ConcurrentDictionary scoped per circuitFor non-page components:
@inject SessionShim Session
@code {
private string GetUserId() => Session["UserId"]?.ToString() ?? "guest";
}
ViewState is component-instance state. Use normal C# fields/properties:
// Web Forms
ViewState["CurrentPage"] = pageIndex;
var page = (int)ViewState["CurrentPage"];
// Blazor
private int currentPage;
Application-wide state becomes singleton services:
// AppStateService.cs
public class AppStateService
{
private readonly ConcurrentDictionary<string, object> _state = new();
public void Set(string key, object value) => _state[key] = value;
public T? Get<T>(string key) => _state.TryGetValue(key, out var val) ? (T)val : default;
}
// Program.cs
builder.Services.AddSingleton<AppStateService>();
| Web Forms | Blazor Equivalent | Scope |
|---|---|---|
Session["key"] | Scoped service | Per-circuit (lost on disconnect) |
Session["key"] (persistent) | ProtectedSessionStorage | Browser session tab |
Application["key"] | Singleton service | App-wide |
Cache["key"] | IMemoryCache or IDistributedCache | Configurable |
ViewState["key"] | Component fields/properties | Per-component |
TempData["key"] | ProtectedSessionStorage | One read |
Cookies | ProtectedLocalStorage or HTTP endpoints | Browser |
@inject ProtectedSessionStorage SessionStorage
@code {
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
var result = await SessionStorage.GetAsync<ShoppingCart>("cart");
cart = result.Success ? result.Value! : new ShoppingCart();
}
}
private async Task SaveCart()
{
await SessionStorage.SetAsync("cart", cart);
}
}
Note:
ProtectedSessionStorageonly works after the first render (it requires JS interop). Always check inOnAfterRenderAsync, notOnInitializedAsync.
Architecture migration patterns (Global.asax, Web.config, routes, handlers, enhanced navigation) are in the child document:
Blazor Server circuits are long-lived. Always use IDbContextFactory and create short-lived DbContext instances per operation.
WRONG — IQueryable returned from disposed context:
private IQueryable<Product> GetProducts(int categoryId)
{
using var db = DbFactory.CreateDbContext();
return db.Products.Where(p => p.CategoryId == categoryId); // Context disposed before query executes!
}
RIGHT — materialize inside using block:
private IQueryable<Product> GetProducts(int categoryId)
{
using var db = DbFactory.CreateDbContext();
var results = db.Products
.Where(p => p.CategoryId == categoryId)
.ToList(); // Execute query NOW while context is alive
return results.AsQueryable(); // Return materialized data as IQueryable
}
For SelectHandler delegates, the delegate is invoked by BWFC infrastructure AFTER your method returns. You MUST materialize:
// BWFC SelectHandler delegate — MUST materialize
private IQueryable<Product> SelectProducts(int maxRows, int startRowIndex,
string sortByExpression, out int totalRowCount)
{
using var db = DbFactory.CreateDbContext();
totalRowCount = db.Products.Count();
var results = db.Products
.OrderBy(p => p.Name)
.Skip(startRowIndex)
.Take(maxRows)
.ToList(); // CRITICAL — materialize NOW
return results.AsQueryable();
}
Web Forms SelectMethod runs inside a page lifecycle. Blazor doesn't have this. Use explicit transaction scopes in services if needed:
using var db = factory.CreateDbContext();
using var transaction = await db.Database.BeginTransactionAsync();
// ... operations
await transaction.CommitAsync();
Web Forms SelectMethod returns IQueryable synchronously. Blazor services should be async:
// WRONG: return db.Products.ToList();
// RIGHT: return await db.Products.ToListAsync();
ConfigurationManager.AppSettings["key"] works via BWFC's ConfigurationManager shim. Call app.UseConfigurationManagerShim() in Program.cs to bind it to IConfiguration. For new code, prefer injecting IConfiguration or using the Options pattern.
Web Forms often has static helper classes that access HttpContext.Current. These must be refactored to accept dependencies via constructor injection.
Web Forms throws ThreadAbortException when Response.Redirect(url, true) is called with endResponse=true. Blazor does not throw this exception — ResponseShim.Redirect() silently ignores the endResponse parameter. Any catch (ThreadAbortException) blocks become dead code after migration. Review and remove them. Code that runs AFTER Response.Redirect(url, true) will execute in Blazor (unlike Web Forms where execution stopped).
Minimal APIs are for real HTTP endpoints (REST APIs, webhooks), NOT for migrating Web Forms page actions.
WRONG:
// Program.cs — creating API endpoint for a page action
app.MapPost("/api/cart/add", async (CartItem item, CartService cart) =>
{
cart.Add(item);
return Results.Ok();
});
// Cart.razor — calling the API
await Http.PostAsJsonAsync("/api/cart/add", item);
RIGHT:
// Cart.razor — just call the service directly
@inject CartService CartService
<button @onclick="() => CartService.Add(item)">Add to Cart</button>
When Minimal APIs ARE appropriate:
When they are NOT appropriate:
You already have Session via WebFormsPageBase or @inject SessionShim.
WRONG:
@inject IHttpContextAccessor HttpContextAccessor
var session = HttpContextAccessor.HttpContext?.Session;
var cartId = session?.GetString("CartId");
RIGHT:
@inherits WebFormsPageBase
var cartId = Session["CartId"]?.ToString();
If the original Web Forms code used Session["key"], use SessionShim. Don't invent cookie-based workarounds.
WRONG:
// Creating cookie-based cart ID because "Session doesn't work in Blazor"
Response.Cookies.Append("CartId", Guid.NewGuid().ToString());
var cartId = Request.Cookies["CartId"];
RIGHT:
// SessionShim handles the storage — just use Session
Session["CartId"] = Guid.NewGuid().ToString();
var cartId = Session["CartId"]?.ToString();
There is no HttpContext.Current in ASP.NET Core. Use the Session property.
WRONG:
HttpContext.Current.Session["UserId"] = userId;
RIGHT:
Session["UserId"] = userId; // From WebFormsPageBase or injected SessionShim