Vivavoy Learning

Bài giảng 1: Khởi đầu với .NET MAUI Blazor Hybrid và Blazor Web App

Mục tiêu: Cài môi trường bằng Visual Studio Code, tạo và chạy 2 dự án mẫu — .NET MAUI Blazor Hybrid (app đa nền tảng) và Blazor Web App (web). Bạn sẽ sửa được giao diện, thêm nút đếm, và hiểu khác biệt giữa hai mô hình.

1) Điều kiện tiên quyết

  • Hệ điều hành: Windows 10/11 (khuyến nghị). macOS dùng được cho iOS, nhưng hướng dẫn dưới đây tập trung Windows + Android.
  • Visual Studio Code (mới nhất) + các extension:
    • C# (ms-dotnettools.csharp)
    • .NET Install Tool (ms-dotnettools.vscode-dotnet-runtime) — tùy chọn
    • Razor (ms-dotnettools.razor) — nếu chưa có
  • .NET SDK 8.x (bắt buộc). Kiểm tra bằng lệnh dotnet --info.
  • Workload MAUI cho .NET:
    • Cài bằng lệnh: dotnet workload install maui
  • Android build & emulator (để chạy MAUI trên Android):
    • Microsoft OpenJDK 17 (JDK 17)
    • Android SDK + Emulator (khuyên dùng Android Studio để cài SDK và tạo AVD)
  • Tùy chọn Windows target: muốn chạy MAUI bản Windows cần Windows SDK/Windows App SDK. Nếu chưa sẵn, hãy ưu tiên chạy Android cho đơn giản.
  • iOS: cần máy Mac với Xcode. Trên Windows, tập trung Android/Windows.

2) Cài đặt môi trường (từng bước, ngắn gọn)

  1. Cài .NET SDK 8 → mở Terminal/PowerShell: 
    dotnet --info

    Thấy version 8.x là đạt. Nếu chưa, cài .NET 8 rồi kiểm tra lại.

  2. Cài workload MAUI: 
    dotnet workload install maui

    Sau khi cài, có thể kiểm tra: 

    dotnet workload list

  3. Cài JDK 17 (ví dụ qua winget trên Windows): 
    winget install --id Microsoft.OpenJDK.17 -e
  4. Cài Android SDK + Emulator:
    • Cài Android Studio (dùng để quản lý SDK/emulator).
    • Mở Android Studio → More Actions → SDK Manager:
      • Cài Android SDK Platform (API 33 hoặc 34), Android SDK Build-Tools, Platform-Tools.
    • Mở AVD Manager → tạo emulator (ví dụ Pixel 5, API 33/34).

    Lưu ý đường dẫn SDK: thường là C:\Users\<tên-bạn>\AppData\Local\Android\Sdk. Nếu cần, đặt biến môi trường ANDROID_SDK_ROOT trỏ tới thư mục này.

  5. Bật ảo hóa nếu emulator không chạy: bật Hyper-V/Virtual Machine Platform trong Windows Features, rồi khởi động lại.

3) Nắm khái niệm cốt lõi

  • .NET: nền tảng phát triển ứng dụng (web, desktop, mobile).
  • C#: ngôn ngữ chính trong hệ .NET.
  • Blazor: xây UI bằng component .razor với C# thay vì JavaScript.
  • Blazor Web App: app web chạy trong trình duyệt, server/interactive.
  • .NET MAUI Blazor Hybrid: app native (Android/iOS/Windows/macOS) nhúng Blazor qua WebView, có thể truy cập API thiết bị.

4) Thực hành A — Tạo .NET MAUI Blazor Hybrid (dùng VS Code + CLI)

4.1 Tạo và chạy dự án

  1. Mở Terminal tại thư mục bạn muốn chứa dự án, chạy: 
    dotnet new maui-blazor -n HelloMauiBlazor
cd HelloMauiBlazor
  2. Mở thư mục trong VS Code: 
    code .
  3. Chạy trên Android (đã mở emulator sẵn): 
    dotnet run -f net8.0-android

    Nếu lần đầu hơi lâu là bình thường (restore, build, deploy).

  4. Tùy chọn chạy Windows (nếu đã có Windows SDK): 
    dotnet run -f net8.0-windows10.0.19041.0

4.2 Cấu trúc dự án (đọc nhanh)

  • MainPage.xaml: chứa BlazorWebView hiển thị UI Blazor.
  • wwwroot/index.html: trang host cho Blazor trong MAUI.
  • Components/*.razor: component UI (ví dụ Main.razor, Counter.razor).
  • Platforms/*: cấu hình theo nền tảng (Android/iOS/Windows/macOS).

4.3 Chỉnh sửa đầu tiên (Hello + Counter)

  1. Mở file Components/Main.razor và thay nội dung bằng:
<h2>Xin chào từ .NET MAUI Blazor Hybrid!</h2>

<p>Bạn đang chạy UI Blazor bên trong ứng dụng MAUI native.</p>

<button @onclick="Increment">Bấm để đếm</button>
<p>Số lần bấm: @count</p>

@code {
  int count = 0;
  void Increment() => count++;
}

Lưu file, rồi chạy lại lệnh phù hợp nền tảng (Android/Windows) để xem kết quả.

4.4 Điều hướng một trang mới

  1. Thêm file Components/About.razor: 
    @page "/about"
@* Thêm nhận diện thiết bị *@
@using MauiApp1.Shared.Services
@inject IFormFactor FormFactor

<h3>About</h3>
<p>Đây là trang giới thiệu trong app MAUI Blazor Hybrid.</p>
<a href="/">Quay lại trang chính</a>
  2. Mở Components/Main.razor, thêm link: 
    <a href="/about">Đi đến About</a>
  3. Mở hoặc tạo file định tuyến nếu template dùng Router trong wwwroot/index.html hoặc cấu hình ở App.razor. Với mẫu MAUI Blazor (Routes.razor), router đã có sẵn. Nếu cần, đảm bảo có: 
    <Router AppAssembly="typeof(App).Assembly">
  <Found Context="routeData">
    <RouteView RouteData="routeData" />
  </Found>
  <NotFound>
    <h1>Not found</h1>
  </NotFound>
</Router>

5) Thực hành B — Tạo Blazor Web App (web, chạy trình duyệt)

5.1 Tạo và chạy dự án

  1. Mở Terminal tại thư mục làm việc: 
    dotnet new blazor -n HelloBlazorWeb
cd HelloBlazorWeb
code .
  2. Chạy server (kèm reload khi sửa): 
    dotnet watch run

    Trình duyệt sẽ mở trang web. Khi sửa file .razor, trang tự reload.

5.2 Sửa trang đầu tiên

  1. Mở trang chính (thường là Pages/Home.razor hoặc Components/Pages/Home.razor tùy template) và thay nội dung:
<h2>Xin chào từ Blazor Web App!</h2>

<button @onclick="Increment">Bấm để đếm</button>
<p>Số lần bấm: @count</p>

@code {
  int count = 0;
  void Increment() => count++;
}

5.3 Thêm trang About

  1. Tạo Pages/About.razor: 
    <h3>About</h3>
<p>Đây là trang giới thiệu trong Blazor Web App.</p>
<a href="/">Về trang chủ</a>
  2. Thêm link vào menu (ví dụ trong Components/Layout/NavMenu.razor hoặc tương đương): 
    <NavLink href="/about" Match="NavLinkMatch.All">About</NavLink>

6) Bài tập mini (làm ngay cho “lên tay”)

  • Mini 1: Biến nút đếm thành 2 nút: Tăng/Giảm, không giảm dưới 0.
  • Mini 2: Tạo component dùng chung MessageCard.razor nhận tham số Title và Body, dùng ở cả hai dự án.
  • Mini 3: Thêm thanh điều hướng đơn giản (các link đến Home/About) cho cả hai dự án.

7) Kiểm tra nhanh (tự trả lời)

  1. Khác biệt: Blazor Web App chạy trong trình duyệt; MAUI Blazor Hybrid chạy trong app native và có thể gọi API thiết bị.
  2. BlazorWebView: dùng để host UI Blazor bên trong trang XAML của MAUI.
  3. Tái sử dụng component: vì cùng dùng Razor/C# nên component có thể dùng ở cả Hybrid và Web (chỉ tránh gọi API đặc thù nền tảng trong component dùng chung).

8) Sự cố thường gặp và cách xử lý

  • Không thấy template: chạy lại dotnet workload install maui (và dotnet --info để chắc đang ở .NET 8).
  • Lỗi Android build: kiểm tra JDK 17, Android SDK/Build-Tools/Platform-Tools đã cài; đặt ANDROID_SDK_ROOT đúng; mở emulator trước khi dotnet run -f net8.0-android.
  • Emulator không khởi động: bật ảo hóa (Hyper-V/Virtual Machine Platform) và cập nhật system image API 33/34 trong Android Studio.
  • Chạy Windows target lỗi: tạm dùng Android; sau sẽ bổ sung Windows SDK. Mục tiêu bài này là chạy được Android + Web.
  • Không “hot reload” trong MAUI khi dùng CLI: sau khi sửa code, build/run lại lệnh tương ứng. Với Blazor Web App dùng dotnet watch run để tự reload.

9) Bạn hoàn thành khi

  • Đã chạy HelloMauiBlazor trên Android emulator (hoặc Windows nếu có SDK).
  • Đã chạy HelloBlazorWeb trên trình duyệt với dotnet watch run.
  • Đã sửa component để có nút đếm ở cả hai dự án.
  • Đã tạo trang About và điều hướng đến nó.

10) Hướng tới Bài 2

Sang bài sau: tổ chức dự án (layout, routing), MVVM cơ bản (MAUI), và lưu trữ dữ liệu đơn giản (Preferences/file). Trước khi qua bài 2, hãy hoàn thành checklist trên.

Phụ lục dưới cùng — Gói gọn cho Visual Studio Code

A. Extension nên cài

  • C# (ms-dotnettools.csharp): IntelliSense, debug C#.
  • Razor (ms-dotnettools.razor): hỗ trợ file .razor.
  • .NET Install Tool (ms-dotnettools.vscode-dotnet-runtime): hỗ trợ runtime nếu thiếu.

B. Lệnh nhanh cần nhớ

  • Kiểm tra .NET: 
    dotnet --info
  • Cài MAUI workload: 
    dotnet workload install maui
  • Tạo MAUI Blazor: 
    dotnet new maui-blazor -n HelloMauiBlazor
  • Chạy MAUI Android: 
    dotnet run -f net8.0-android
  • Tạo Blazor Web App: 
    dotnet new blazor -n HelloBlazorWeb
  • Chạy web (auto reload): 
    dotnet watch run

C. Cấu hình Android SDK nhanh

  • Đường dẫn SDK mặc định (Windows): C:\Users\<tên-bạn>\AppData\Local\Android\Sdk
  • Biến môi trường: đặt ANDROID_SDK_ROOT đến đường dẫn trên (Log out/in nếu cần).
  • AVD: tạo bằng AVD Manager trong Android Studio (chọn API 33/34).

Khi bạn sẵn sàng, nói mình biết bạn đang ở bước nào để mình hướng dẫn bước kế tiếp “cầm tay chỉ việc”.