Umbraco: Hướng dẫn cài đặt Umbraco 13 với .NET 8 và SQL Server Express - Day 1

Umbraco là một hệ thống quản trị nội dung (Content Management System – CMS) mã nguồn mở được xây dựng trên nền tảng .NET. Umbraco cho phép developer xây dựng website, quản lý nội dung và phát triển các giải pháp CMS tùy chỉnh bằng hệ sinh thái ASP.NET Core.

Trong bài viết này, chúng ta sẽ tạo một project Umbraco 13 bằng .NET CLI, cấu hình SQL Server Express sử dụng Windows Authentication, chạy ứng dụng và hoàn tất quá trình cài đặt Backoffice.

1. Chuẩn bị môi trường

Trước khi bắt đầu, hãy đảm bảo máy tính đã cài đặt các công cụ sau:

• .NET 8 SDK.
• Visual Studio 2022 hoặc Visual Studio Code.
• SQL Server Express.
• SQL Server Management Studio (SSMS).
• PowerShell hoặc Windows Terminal.

Trong bài hướng dẫn này, chúng ta sử dụng cấu hình:

Thành phần	Giá trị
Umbraco CMS	13.8.1
.NET	.NET 8
SQL Server instance	.\SQLEXPRESS
Authentication	Windows Authentication
Database	MyUmbracoSite
Project name	MyUmbracoSite

Umbraco 13 hỗ trợ .NET 8 và có thể sử dụng SQL Server hoặc SQLite làm cơ sở dữ liệu. Trong bài viết này, chúng ta chọn SQL Server Express để thực hành cấu hình database tương tự môi trường phát triển thực tế.

Tài liệu chính thức: Umbraco 13 Requirements.

2. Cài đặt Umbraco Project Template

Khác với Umbraco 8, chúng ta không cần tạo một ASP.NET Empty Project rồi cài package UmbracoCms thông qua NuGet Package Manager.

Với Umbraco 13, cách đơn giản là sử dụng project template được cung cấp bởi Umbraco và .NET CLI.

Mở PowerShell và di chuyển đến thư mục dùng để lưu source code:

cd D:\Practices\Umbraco\getting-started

Tiếp theo, cài đặt template Umbraco phiên bản 13.8.1:

dotnet new install Umbraco.Templates@13.8.1

Trong cú pháp trên, ký tự @ được sử dụng để chỉ định phiên bản package template cần cài đặt.

Ví dụ:

dotnet new install Umbraco.Templates@13.8.1

Ở các phiên bản .NET CLI mới, cú pháp PackageName@Version được ưu tiên thay cho cú pháp cũ sử dụng ::.

Nếu cài đặt thành công, terminal sẽ hiển thị danh sách template tương tự:

Template Name        Short Name
Umbraco Package      umbracopackage
Umbraco Package RCL  umbracopackage-rcl
Umbraco Project      umbraco

Template umbraco là template dùng để tạo một project Umbraco CMS mới.

Nếu muốn kiểm tra các template hiện có, bạn có thể chạy:

dotnet new list

3. Tạo project Umbraco 13

Sau khi cài đặt template, tạo project mới bằng lệnh:

dotnet new umbraco --name MyUmbracoSite --version 13.8.1

Trong đó:

• dotnet new umbraco: sử dụng Umbraco Project Template.
• --name MyUmbracoSite: đặt tên project là MyUmbracoSite.
• --version 13.8.1: chỉ định phiên bản Umbraco CMS mà project sử dụng.

Việc chỉ định phiên bản CMS giúp project sử dụng đúng phiên bản mong muốn thay vì phụ thuộc vào phiên bản mặc định của template.

Sau khi tạo project thành công, cấu trúc thư mục cơ bản sẽ tương tự như sau:

getting-started/
└── MyUmbracoSite/
    ├── Controllers/
    ├── Views/
    ├── wwwroot/
    ├── appsettings.json
    ├── Program.cs
    └── MyUmbracoSite.csproj

Cấu trúc thực tế có thể khác đôi chút tùy phiên bản template và các tùy chọn được sử dụng.

Di chuyển vào thư mục project:

cd MyUmbracoSite

Kiểm tra file MyUmbracoSite.csproj để xác nhận phiên bản package Umbraco CMS được tham chiếu trong project.

4. Build và chạy thử project

Trước khi cấu hình database, hãy kiểm tra project vừa tạo có thể restore package và build thành công hay không.

dotnet restore
dotnet build

Nếu quá trình build thành công, chạy ứng dụng bằng lệnh:

dotnet run

Terminal sẽ hiển thị địa chỉ ứng dụng, ví dụ:

Now listening on: https://localhost:44388

Địa chỉ và port thực tế sẽ phụ thuộc vào môi trường chạy ứng dụng. Mở URL được hiển thị trong terminal để truy cập website.

Để dừng ứng dụng, nhấn Ctrl + C trong terminal.

5. Tạo database trong SQL Server Express

Bây giờ, chúng ta sẽ cấu hình SQL Server Express làm database cho Umbraco.

5.1. Kết nối SQL Server bằng SSMS

Mở SQL Server Management Studio (SSMS), sau đó chọn các thông tin kết nối:

• Server type: Database Engine.
• Server name: .\SQLEXPRESS.
• Authentication: Windows Authentication.

Nhấn Connect để kết nối tới SQL Server Express.

Nếu không kết nối được, hãy kiểm tra dịch vụ SQL Server (SQLEXPRESS) trong Windows Services và bảo đảm dịch vụ đang chạy.

5.2. Tạo database

Trong SSMS, mở cửa sổ New Query và chạy câu lệnh:

USE master;
GO

IF DB_ID(N'MyUmbracoSite') IS NULL
BEGIN
    CREATE DATABASE MyUmbracoSite;
END;
GO

Sau khi chạy thành công, database MyUmbracoSite sẽ xuất hiện trong thư mục Databases của Object Explorer.

Lưu ý: Tài khoản Windows đang thực hiện câu lệnh phải có quyền tạo database. Nếu database đã tồn tại, không cần tạo lại.

6. Cấu hình connection string trong appsettings.json

Trong ASP.NET Core, connection string thường được đặt trong section ConnectionStrings của file appsettings.json.

Umbraco sử dụng key umbracoDbDSN để xác định connection string của database chính.

Mở file appsettings.json trong project MyUmbracoSite và bổ sung cấu hình sau:

{
  "$schema": "appsettings-schema.json",
  "ConnectionStrings": {
    "umbracoDbDSN": "Server=.\\SQLEXPRESS;Database=MyUmbracoSite;Integrated Security=True;Encrypt=True;TrustServerCertificate=True",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.SqlClient"
  },
  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "System": "Warning"
      }
    }
  },
  "Umbraco": {
    "CMS": {
      "Global": {
        "Id": "e7fad35d-c925-40c8-8414-77cbbae3d0fa",
        "SanitizeTinyMce": true
      },
      "Content": {
        "AllowEditInvariantFromNonDefault": true,
        "ContentVersionCleanupPolicy": {
          "EnableCleanup": true
        }
      },
      "Unattended": {
        "UpgradeUnattended": true
      },
      "Security": {
        "AllowConcurrentLogins": false
      }
    }
  }
}

Nếu file hiện tại đã có các section Serilog và Umbraco, bạn chỉ cần bổ sung section ConnectionStrings ở cùng cấp với hai section đó.

6.1. Giải thích connection string

• Server=.\\SQLEXPRESS: kết nối tới SQL Server Express trên máy local. Trong JSON, dấu gạch chéo ngược phải được escape thành \\.
• Database=MyUmbracoSite: tên database sẽ sử dụng.
• Integrated Security=True: sử dụng Windows Authentication, không cần khai báo username và password SQL Server.
• Encrypt=True: bật mã hóa kết nối.
• TrustServerCertificate=True: bỏ qua xác thực chứng chỉ máy chủ. Thiết lập này thường được dùng khi phát triển local với certificate chưa được máy tính tin cậy.
• umbracoDbDSN_ProviderName: xác định SQL Server provider.

Không nên sử dụng TrustServerCertificate=True như một giải pháp mặc định cho production. Môi trường production nên sử dụng chứng chỉ máy chủ hợp lệ và cấu hình xác thực phù hợp.

7. Kiểm tra SQL Server và database

Trước khi chạy Umbraco, có thể kiểm tra SQL Server bằng một câu truy vấn đơn giản trong SSMS:

SELECT
    @@SERVERNAME AS ServerName,
    DB_NAME() AS DatabaseName,
    SUSER_SNAME() AS LoginName;

Kết quả giúp xác nhận instance SQL Server đang kết nối, database đang được chọn và tài khoản đăng nhập hiện tại.

Tiếp theo, cần bảo đảm tài khoản Windows chạy ứng dụng có quyền đọc, ghi dữ liệu và tạo hoặc cập nhật schema trong database.

Trong môi trường phát triển local, có thể cấp role db_owner cho tài khoản ứng dụng trên riêng database MyUmbracoSite để đơn giản hóa quá trình cài đặt. Không cần cấp quyền sysadmin chỉ để chạy Umbraco.

Nếu ứng dụng chạy bằng dotnet run trong terminal, kết nối Windows Authentication thường sử dụng danh tính Windows của tài khoản chạy tiến trình. Khi chạy từ Visual Studio, hãy kiểm tra tài khoản đang chạy ứng dụng nếu gặp lỗi quyền truy cập.

8. Hoàn tất cài đặt Umbraco

Sau khi cấu hình connection string, chạy lại ứng dụng:

dotnet build
dotnet run

Mở URL localhost được hiển thị trong terminal. Nếu đây là project mới chưa được cài đặt, Umbraco sẽ đưa bạn đến trình hướng dẫn cài đặt.

Thực hiện theo các bước trên màn hình để:

1. Thiết lập tài khoản quản trị.
2. Chọn hoặc xác nhận database SQL Server.
3. Hoàn tất quá trình cài đặt.
4. Đăng nhập vào Umbraco Backoffice.

Nếu trình cài đặt yêu cầu nhập thông tin database, hãy sử dụng SQL Server instance và database đã tạo ở các bước trước. Không nên tiếp tục với cấu hình database khác nếu mục tiêu là sử dụng MyUmbracoSite.

Sau khi cài đặt thành công, bạn có thể truy cập Backoffice theo URL:

https://localhost:PORT/umbraco

Thay PORT bằng port thực tế được terminal hiển thị. Sử dụng tài khoản quản trị mà bạn đã tạo trong quá trình cài đặt.

9. Kiểm tra database sau khi cài đặt

Mở SSMS và refresh database MyUmbracoSite.

Sau khi Umbraco hoàn tất quá trình khởi tạo, database sẽ chứa các bảng phục vụ quản lý nội dung, người dùng, cấu hình và các dữ liệu nội bộ khác của CMS.

Bạn có thể kiểm tra danh sách bảng bằng truy vấn:

USE MyUmbracoSite;
GO

SELECT TABLE_SCHEMA, TABLE_NAME
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_TYPE = 'BASE TABLE'
ORDER BY TABLE_SCHEMA, TABLE_NAME;

Nếu các bảng Umbraco đã được tạo, đó là dấu hiệu cho thấy quá trình cài đặt đã khởi tạo schema thành công.

10. Quy trình cài đặt tổng quát

Sơ đồ dưới đây tóm tắt quy trình từ cài template đến khi đăng nhập Backoffice.

flowchart TD A["Cài Umbraco Template 13.8.1"] --> B["Tạo project bằng dotnet new"] B --> C["Build và chạy thử"] C --> D["Tạo database SQL Server"] D --> E["Cấu hình connection string"] E --> F["Chạy Umbraco"] F --> G["Hoàn tất Installation Wizard"] G --> H["Đăng nhập Backoffice"] H --> I["Kiểm tra database và bảng"]

11. Các lỗi thường gặp

11.1. Không tìm thấy SQL Server instance

Nếu gặp lỗi kết nối như SQL Server Error 26, hãy kiểm tra:

• Tên server có chính xác là .\SQLEXPRESS hay không.
• Dịch vụ SQL Server (SQLEXPRESS) có đang chạy hay không.
• SSMS có kết nối được bằng chính server name đó hay không.

11.2. Không mở được database

Nếu gặp lỗi Cannot open database, hãy xác nhận database MyUmbracoSite đã tồn tại và tên database trong connection string được viết chính xác.

11.3. Login failed

Nếu gặp lỗi Login failed for user, hãy kiểm tra danh tính Windows chạy ứng dụng và quyền truy cập database. Windows Authentication không tự động bảo đảm tài khoản có quyền trên mọi database.

11.4. Lỗi chứng chỉ hoặc SSL

Nếu môi trường local gặp lỗi xác thực chứng chỉ, hãy kiểm tra cấu hình mã hóa và chứng chỉ SQL Server. Thiết lập TrustServerCertificate=True có thể giúp môi trường development hoạt động, nhưng không nên dùng để bỏ qua xác thực chứng chỉ trong production.

11.5. Không thấy trình cài đặt Umbraco

Hãy kiểm tra log trong terminal, connection string và trạng thái cài đặt hiện tại. Nếu ứng dụng đã được cài đặt trước đó, Umbraco có thể hiển thị trang website hoặc màn hình đăng nhập thay vì chạy lại installation wizard.

12. Kết luận

Trong bài viết này, chúng ta đã tạo một project Umbraco 13.8.1 trên .NET 8 bằng .NET CLI, cấu hình SQL Server Express sử dụng Windows Authentication và hoàn tất các bước cài đặt CMS.

So với cách cài Umbraco 8 bằng ASP.NET Empty Project và NuGet Package Manager, cách tiếp cận mới đơn giản hơn vì project được tạo từ template chính thức, sử dụng ASP.NET Core và có thể chạy trực tiếp bằng .NET CLI hoặc Visual Studio.

Sau khi hoàn tất cài đặt, bạn có thể tiếp tục tìm hiểu các khái niệm quan trọng như Document Types, Data Types, Content, Templates và cách xây dựng website trên Umbraco.

Nếu mục tiêu là xây dựng ứng dụng Headless CMS, bước tiếp theo là tìm hiểu Content Delivery API và cách để frontend như Next.js truy xuất nội dung từ Umbraco.

Tài liệu tham khảo

• Umbraco 13 – Installation
• Umbraco 13 – Install using Visual Studio
• Umbraco 13 – Connection Strings Settings
• Umbraco 13 – Requirements