ASP.NET Core MVC에서 Playwright.NET으로 HTML 특정 영역을 이미지로 캡처하기
ASP.NET Core MVC 애플리케이션에서 HTML 전체 페이지가 아니라 특정 HTML 영역만 이미지로 캡처해야 하는 경우가 있습니다.
예를 들어 다음과 같은 용도로 활용할 수 있습니다.
- 전자 서명 영역 이미지 생성
- 계약서 또는 동의서 일부를 이미지로 보관
- HTML 기반 리포트를 PNG로 변환
- 이미지 데이터를 Azure Blob Storage에 저장
- 생성된 이미지를 Base64로 변환하여 외부 API로 전송
- 이후 동일 HTML을 PDF로 생성
이 글에서는 Microsoft Playwright.NET과 Chromium을 이용하여 ASP.NET Core MVC 서버에서 HTML을 렌더링하고, 특정 <div> 영역만 PNG 이미지로 캡처하는 방법을 살펴봅니다.
예제 프로젝트는 ASP.NET Core MVC / .NET 10 기반 DotNetNote를 사용합니다.
1. Playwright.NET을 사용하는 이유
HTML을 이미지로 변환하는 방법은 여러 가지가 있습니다.
브라우저에서 JavaScript 라이브러리인 html2canvas를 사용할 수도 있지만, 서버에서 일관된 결과물을 생성해야 하는 경우에는 실제 Chromium 브라우저 엔진을 사용하는 Playwright가 유용합니다.
Playwright.NET을 사용하면 다음과 같은 작업이 가능합니다.
HTML
↓
Chromium
↓
Browser Rendering
↓
특정 DOM Element 선택
↓
PNG Screenshot
↓
byte[]
특히 전체 화면이 아니라 원하는 요소만 선택하여 캡처할 수 있습니다.
var target = page.Locator("#capture-target");
byte[] imageBytes = await target.ScreenshotAsync();
결과가 바로 byte[]이므로 파일 저장, Blob Storage 업로드, Base64 변환 등에 쉽게 사용할 수 있습니다.
2. Microsoft.Playwright NuGet 패키지 설치
먼저 ASP.NET Core 프로젝트에 Microsoft.Playwright 패키지를 설치합니다.
Visual Studio의 Package Manager Console을 사용하는 경우:
Install-Package Microsoft.Playwright
.NET CLI를 사용하는 경우:
dotnet add package Microsoft.Playwright
패키지를 설치한 후 반드시 프로젝트를 한 번 빌드합니다.
dotnet build
빌드를 수행하면 출력 폴더에 Playwright 브라우저 설치 스크립트인 playwright.ps1이 생성됩니다.
.NET 10 Debug 빌드를 기준으로 다음과 같은 위치에서 확인할 수 있습니다.
bin\Debug\net10.0\playwright.ps1
3. PowerShell 7 설치
Playwright의 브라우저 설치 스크립트를 실행하려면 pwsh 명령을 사용할 수 있어야 합니다.
Windows에 기본 포함된 Windows PowerShell 5.x만 설치되어 있는 경우 다음과 같은 오류가 발생할 수 있습니다.
'pwsh' 용어가 cmdlet, 함수, 스크립트 파일 또는
실행할 수 있는 프로그램 이름으로 인식되지 않습니다.
이 경우 PowerShell 7을 설치합니다.
Windows Package Manager를 사용하는 경우:
winget install --id Microsoft.PowerShell --source winget
설치 후 새로운 터미널을 실행하고 다음 명령으로 확인합니다.
pwsh --version
정상적으로 버전이 출력되면 준비가 완료된 것입니다.
4. 로컬 개발 환경에 Chromium 설치
Microsoft.Playwright NuGet 패키지를 설치했다고 해서 Chromium 브라우저까지 자동으로 설치되는 것은 아닙니다.
프로젝트를 빌드한 후 다음 명령을 실행합니다.
.NET 10 Debug 환경:
pwsh .\bin\Debug\net10.0\playwright.ps1 install chromium
Release 환경이라면:
pwsh .\bin\Release\net10.0\playwright.ps1 install chromium
설치된 브라우저 목록은 다음과 같이 확인할 수 있습니다.
pwsh .\bin\Debug\net10.0\playwright.ps1 install --list
Playwright 패키지는 실행 API를 제공하고, 실제 Chromium 실행 파일은 별도로 설치된다는 점이 중요합니다.
5. Playwright 테스트 Controller 만들기
다음 Controller를 생성합니다.
Controllers/PlaywrightTestController.cs
예제 코드는 다음과 같습니다.
using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.Playwright;
namespace DotNetNote.Controllers
{
/// <summary>
/// Playwright.NET을 사용하여 Chromium에서 HTML을 렌더링하고
/// 특정 HTML 요소만 PNG 이미지로 캡처하는 데모 컨트롤러입니다.
/// </summary>
public class PlaywrightTestController : Controller
{
private const string CaptureTargetSelector = "#capture-target";
private readonly ILogger<PlaywrightTestController> logger;
public PlaywrightTestController(
ILogger<PlaywrightTestController> logger)
{
this.logger = logger;
}
/// <summary>
/// Playwright Chromium을 실행하여 특정 HTML 영역만
/// PNG 이미지로 캡처합니다.
/// </summary>
[HttpGet]
public async Task<IActionResult> Index()
{
try
{
using var playwright = await Playwright.CreateAsync();
await using var browser =
await playwright.Chromium.LaunchAsync(
new BrowserTypeLaunchOptions
{
Headless = true
});
var page = await browser.NewPageAsync(
new BrowserNewPageOptions
{
ViewportSize = new ViewportSize
{
Width = 1200,
Height = 800
}
});
await page.SetContentAsync(
TestHtml,
new PageSetContentOptions
{
WaitUntil = WaitUntilState.Load
});
var target =
page.Locator(CaptureTargetSelector);
var imageBytes =
await target.ScreenshotAsync(
new LocatorScreenshotOptions
{
Type = ScreenshotType.Png
});
ViewBag.Success = true;
ViewBag.ImageBase64 =
Convert.ToBase64String(imageBytes);
ViewBag.ImageSize =
imageBytes.Length;
ViewBag.ErrorMessage = null;
}
catch (Exception ex)
{
this.logger.LogError(
ex,
"Playwright.NET screenshot test failed.");
ViewBag.Success = false;
ViewBag.ImageBase64 = null;
ViewBag.ImageSize = 0;
ViewBag.ErrorMessage = ex.Message;
}
return this.View();
}
/*
/// <summary>
/// Playwright에서 사용할 Chromium 브라우저를 설치합니다.
///
/// 학습 및 배포 환경 확인을 위한 참고용 코드입니다.
/// 실제 공개 사이트에서는 이 액션을 활성화하지 않는 것을 권장합니다.
///
/// Azure App Service 등의 서버에 Chromium이 설치되어 있지 않을 때
/// 일회성 테스트 용도로 사용할 수 있습니다.
/// </summary>
[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult InstallChromium()
{
try
{
var exitCode =
Microsoft.Playwright.Program.Main(
new[]
{
"install",
"chromium"
});
if (exitCode != 0)
{
throw new Exception(
$"Playwright Chromium installation failed. " +
$"ExitCode: {exitCode}");
}
TempData["PlaywrightInstallMessage"] =
"Chromium installed successfully.";
return RedirectToAction(nameof(Index));
}
catch (Exception ex)
{
this.logger.LogError(
ex,
"Playwright Chromium installation failed.");
TempData["PlaywrightInstallError"] =
ex.Message;
return RedirectToAction(nameof(Index));
}
}
*/
/// <summary>
/// Playwright 렌더링 및 특정 요소 캡처 테스트에 사용할 HTML입니다.
/// </summary>
private const string TestHtml = """
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<style>
body {
font-family: Arial, sans-serif;
background: #eeeeee;
padding: 40px;
}
#capture-target {
width: 700px;
background: white;
border: 2px solid #444444;
padding: 30px;
}
.title {
font-size: 22px;
font-weight: bold;
text-align: center;
margin-bottom: 25px;
}
.signature {
margin-top: 30px;
width: 250px;
height: 70px;
border: 1px solid #888888;
display: flex;
align-items: center;
justify-content: center;
font-style: italic;
font-size: 24px;
}
</style>
</head>
<body>
<div>
이 부분은 캡처 대상이 아닙니다.
</div>
<div id="capture-target">
<div class="title">
RELEASE OF INFORMATION AUTHORIZATION
</div>
<p>
This is a simple Playwright.NET screenshot test.
</p>
<p>
Only this HTML section should appear
in the generated image.
</p>
<div class="signature">
Test Signature
</div>
<p>
Date: 2026-08-18
</p>
</div>
<div>
이 부분 역시 캡처 대상이 아닙니다.
</div>
</body>
</html>
""";
}
}
6. 특정 HTML 요소만 캡처하기
이 예제에서 가장 중요한 코드는 다음 부분입니다.
var target =
page.Locator("#capture-target");
var imageBytes =
await target.ScreenshotAsync(
new LocatorScreenshotOptions
{
Type = ScreenshotType.Png
});
HTML 전체 화면에는 다음과 같이 여러 요소가 존재합니다.
<div>
이 부분은 캡처 대상이 아닙니다.
</div>
<div id="capture-target">
캡처할 영역
</div>
<div>
이 부분 역시 캡처 대상이 아닙니다.
</div>
하지만 Playwright의 Locator()를 사용했기 때문에 이미지에는 다음 요소만 포함됩니다.
<div id="capture-target">
...
</div>
전체 페이지를 캡처한 뒤 이미지를 다시 잘라낼 필요가 없습니다.
7. PNG 데이터를 Base64로 변환하기
ScreenshotAsync()의 반환값은 byte[]입니다.
var imageBytes =
await target.ScreenshotAsync();
Base64 문자열이 필요한 경우 다음 한 줄이면 충분합니다.
var base64 =
Convert.ToBase64String(imageBytes);
이번 예제에서는 생성 결과를 바로 확인하기 위해 ViewBag에 Base64 문자열을 전달합니다.
ViewBag.ImageBase64 =
Convert.ToBase64String(imageBytes);
웹 페이지에서는 Data URI로 표시할 수 있습니다.
<img src="data:image/png;base64,..." />
실제 애플리케이션에서는 byte[]을 다음과 같은 여러 방법으로 활용할 수 있습니다.
PNG byte[]
│
├─ 로컬 파일 저장
│
├─ Azure Blob Storage
│
├─ Database varbinary
│
└─ Base64 변환 후 외부 API 전송
8. 결과를 보여주는 MVC View
다음 View를 생성합니다.
Views/PlaywrightTest/Index.cshtml
코드는 다음과 같습니다.
@{
ViewData["Title"] = "Playwright.NET Test";
var success =
ViewBag.Success is bool result &&
result;
}
<div class="container"
style="padding-top:30px; padding-bottom:50px;">
<h2>Playwright.NET Test</h2>
<p>
Playwright.NET과 Chromium을 사용하여 HTML을 렌더링하고
특정 HTML 영역만 PNG 이미지로 캡처하는 예제입니다.
</p>
<hr />
@if (success)
{
<div class="alert alert-success">
<strong>Success!</strong>
Playwright.NET Chromium screenshot
completed successfully.
</div>
<p>
Image Size:
<strong>@ViewBag.ImageSize bytes</strong>
</p>
<h4>Captured Image</h4>
<div style="margin-top:15px;">
<img src="data:image/png;base64,@ViewBag.ImageBase64"
alt="Playwright Screenshot"
style="max-width:100%;
border:1px solid #cccccc;" />
</div>
}
else
{
<div class="alert alert-danger">
<strong>
Playwright.NET Test Failed
</strong>
</div>
@if (!string.IsNullOrWhiteSpace(
ViewBag.ErrorMessage as string))
{
<pre style="white-space:pre-wrap;">@ViewBag.ErrorMessage</pre>
}
}
<hr />
<a asp-controller="PlaywrightTest"
asp-action="Index"
class="btn btn-primary">
Run Test Again
</a>
</div>
9. 로컬에서 테스트하기
애플리케이션을 실행한 후 다음 URL로 이동합니다.
/PlaywrightTest
정상적으로 실행되면 다음 과정이 서버에서 수행됩니다.
HTTP Request
↓
Playwright.CreateAsync()
↓
Headless Chromium 실행
↓
TestHtml 렌더링
↓
#capture-target 선택
↓
PNG Screenshot
↓
byte[]
↓
Base64
↓
MVC View
화면에는 캡처 대상이 아닌 문장은 나타나지 않고 #capture-target 요소만 이미지로 표시되어야 합니다.
10. Azure App Service에 게시했는데 실행되지 않는 경우
로컬에서 잘 동작하더라도 Azure App Service에 게시한 직후 다음과 같은 오류가 발생할 수 있습니다.
Executable doesn't exist at
C:\local\LocalAppData\ms-playwright\...
이 오류는 Playwright.NET 라이브러리가 실행되지 않는다는 의미가 아닙니다.
실제 의미는 다음과 같습니다.
Microsoft.Playwright.dll 있음
Chromium executable 없음
즉 로컬 PC에는 Chromium을 설치했지만 Azure Web App 서버에는 Chromium이 설치되어 있지 않은 것입니다.
Visual Studio Publish는 개발 PC에 설치된 Playwright Chromium을 자동으로 Azure 서버에 설치해 주지 않습니다.
11. Azure 서버에서 Chromium 설치 테스트하기
Playwright는 C# 코드에서도 브라우저 설치 명령을 실행할 수 있습니다.
var exitCode =
Microsoft.Playwright.Program.Main(
new[]
{
"install",
"chromium"
});
종료 코드가 0이 아니면 설치 실패입니다.
if (exitCode != 0)
{
throw new Exception(
$"Playwright Chromium installation failed. " +
$"ExitCode: {exitCode}");
}
이를 이용하여 배포된 서버에서 Chromium 설치 가능 여부를 테스트할 수 있습니다.
예를 들어 임시로 다음 Action을 활성화할 수 있습니다.
[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult InstallChromium()
{
try
{
var exitCode =
Microsoft.Playwright.Program.Main(
new[]
{
"install",
"chromium"
});
if (exitCode != 0)
{
throw new Exception(
$"Playwright Chromium installation failed. " +
$"ExitCode: {exitCode}");
}
TempData["PlaywrightInstallMessage"] =
"Chromium installed successfully.";
return RedirectToAction(nameof(Index));
}
catch (Exception ex)
{
this.logger.LogError(
ex,
"Playwright Chromium installation failed.");
TempData["PlaywrightInstallError"] =
ex.Message;
return RedirectToAction(nameof(Index));
}
}
이 Action을 서버에서 한 번 실행한 후 /PlaywrightTest를 다시 실행합니다.
Azure Windows App Service에서도 다음 과정이 정상적으로 동작한다면 해당 환경에서 Playwright를 사용할 수 있음을 확인할 수 있습니다.
Azure App Service
↓
Microsoft.Playwright
↓
Chromium 설치
↓
Headless Chromium 실행
↓
HTML Rendering
↓
Element Screenshot
↓
PNG byte[]
12. InstallChromium Action은 테스트가 끝나면 비활성화하기
브라우저 설치는 일반 사용자가 호출해야 하는 웹 기능이 아닙니다.
따라서 공개 웹사이트에서는 다음 Action을 계속 활성화해 두지 않는 것이 좋습니다.
InstallChromium()
DotNetNote와 같은 학습용 프로젝트에서는 설치 방법을 참고할 수 있도록 코드 자체를 주석 처리해서 남겨둘 수 있습니다.
/*
[HttpPost]
[ValidateAntiForgeryToken]
public IActionResult InstallChromium()
{
...
}
*/
이렇게 하면 향후 다른 배포 환경에서 Playwright를 테스트할 때 예제 코드로 다시 활용할 수 있습니다.
실제 운영 애플리케이션이라면 Browser 설치는 웹 요청이 아니라 배포 과정 또는 관리자 전용 시스템 관리 기능으로 분리하는 것이 좋습니다.
13. Azure App Service에서 브라우저 저장 위치 고려하기
Playwright Browser는 기본적으로 자체 캐시 영역에 설치됩니다.
Azure App Service에서는 환경에 따라 다음과 같은 로컬 영역이 사용될 수 있습니다.
C:\local\LocalAppData\ms-playwright
이런 로컬 영역은 운영 환경에서 영구 파일 저장 위치로 사용하기에는 적합하지 않을 수 있습니다.
실제 서비스에서는 Playwright가 지원하는 환경 변수인 다음 값을 사용하여 브라우저 위치를 명시적으로 관리하는 방법도 고려할 수 있습니다.
PLAYWRIGHT_BROWSERS_PATH
예를 들어 Azure App Service의 지속 가능한 HOME 경로를 이용하도록 구성할 수 있습니다.
개념적으로는 다음과 같습니다.
PLAYWRIGHT_BROWSERS_PATH
↓
%HOME%\playwright-browsers
↓
Chromium
학습용 테스트에서는 기본 설치 위치를 사용해도 충분하지만, 운영 서비스에서는 배포와 브라우저 버전 관리 방식을 별도로 설계하는 것이 좋습니다.
14. Debug와 Release의 차이는 아니다
Azure 서버에서 다음 오류가 발생했다고 가정해 봅니다.
Executable doesn't exist
이 오류는 애플리케이션을 Release 모드로 게시했기 때문에 발생하는 문제가 아닙니다.
일반적으로 다음 차이 때문입니다.
개발 PC:
Microsoft.Playwright
+
Chromium 설치
↓
Success
Azure Web App:
Microsoft.Playwright
+
Chromium 없음
↓
Executable doesn't exist
따라서 Playwright 사용 시에는 애플리케이션 배포와 Browser 설치를 별개의 단계로 이해해야 합니다.
15. Playwright를 업데이트했을 때 주의할 점
Microsoft.Playwright 패키지를 업데이트하면 새로운 Playwright 버전에 맞는 Browser 버전이 필요할 수 있습니다.
따라서 패키지를 업데이트한 경우 Browser 설치 명령도 다시 실행하는 것이 좋습니다.
pwsh .\bin\Debug\net10.0\playwright.ps1 install chromium
즉 다음 두 요소는 서로 연관되어 있습니다.
Microsoft.Playwright Version
↕
Chromium Version
NuGet 패키지만 업데이트하고 이전 Chromium을 계속 사용하는 방식은 피하는 것이 좋습니다.
16. 현재 예제를 실제 기능으로 확장한다면
현재 테스트에서는 문자열로 작성한 HTML을 사용하고 있습니다.
private const string TestHtml = """
...
""";
실제 업무 시스템에서는 데이터베이스의 데이터를 이용하여 HTML을 생성할 수 있습니다.
예를 들어:
Database
↓
JSON
↓
ViewModel
↓
Razor HTML
↓
Playwright
↓
PNG
전자 서명이 포함된 Application Form을 예로 들면 다음과 같은 구조가 가능합니다.
Application Form
│
├─ Candidate Information
├─ Consent
├─ Signed Date
└─ Signature
↓
Razor HTML
↓
Playwright
↓
특정 Consent 영역
↓
PNG byte[]
생성된 이미지는 Blob Storage에 저장할 수 있습니다.
PNG byte[]
↓
Azure Blob Storage
외부 API에서 Base64 데이터를 요구한다면 전송 시점에 다음과 같이 변환할 수 있습니다.
var base64 =
Convert.ToBase64String(imageBytes);
전체 구조는 다음과 같이 확장할 수 있습니다.
Application JSON
+
Electronic Signature
↓
HTML Rendering
↓
Playwright Chromium
↓
Specific DOM Screenshot
↓
PNG byte[]
↓
Azure Blob Storage
↓
Background Process
↓
Base64 Encoding
↓
External API
17. 향후 PDF로 확장하기
Playwright를 선택하는 또 다른 장점은 같은 HTML 렌더링 구조를 PDF 생성에도 사용할 수 있다는 점입니다.
현재는 특정 요소를 PNG로 만듭니다.
var imageBytes =
await target.ScreenshotAsync();
향후 문서 전체를 PDF로 만들어야 한다면 Playwright의 PDF 생성 기능을 이용하는 방향으로 확장할 수 있습니다.
따라서 애플리케이션 구조를 다음과 같이 분리해 두는 것이 좋습니다.
Data
↓
ViewModel
↓
HTML
↓
Playwright
├─ PNG
└─ PDF
처음에는 PNG가 필요하더라도 HTML 생성과 이미지 저장 로직을 적절히 분리해 두면 PDF 요구사항이 추가되었을 때 변경 범위를 줄일 수 있습니다.
18. 정리
ASP.NET Core MVC에서 Playwright.NET을 이용하면 실제 Chromium 엔진으로 HTML을 렌더링하고 원하는 DOM 요소만 PNG 이미지로 캡처할 수 있습니다.
기본적인 설치 과정은 다음과 같습니다.
Microsoft.Playwright NuGet 설치
↓
dotnet build
↓
PowerShell 7 준비
↓
playwright.ps1 install chromium
↓
Playwright.CreateAsync()
↓
Chromium.LaunchAsync()
↓
SetContentAsync()
↓
Locator()
↓
ScreenshotAsync()
↓
PNG byte[]
로컬에서는 Chromium 설치 스크립트를 직접 실행하면 됩니다.
pwsh .\bin\Debug\net10.0\playwright.ps1 install chromium
Azure App Service와 같은 서버 환경에서는 애플리케이션만 게시해서는 Chromium이 설치되지 않을 수 있으므로 별도의 Browser 설치 과정이 필요할 수 있습니다.
테스트 목적으로는 다음 C# 코드를 통해 서버에서 설치할 수 있습니다.
Microsoft.Playwright.Program.Main(
new[]
{
"install",
"chromium"
});
다만 실제 운영 애플리케이션에서는 이를 일반 웹 기능으로 공개하지 않고 배포 또는 관리자 시스템 관리 영역에서 처리하는 것이 좋습니다.
이번 DotNetNote 예제의 핵심은 다음 한 문장으로 정리할 수 있습니다.
Playwright.NET을 사용하면 ASP.NET Core 서버에서 Chromium으로 HTML을 렌더링하고 특정 HTML 요소만 이미지로 캡처하여 byte[] 형태로 활용할 수 있습니다.
이 byte[]을 기반으로 Azure Blob Storage 저장, Base64 API 전송, 전자서명 증빙 생성, HTML 문서의 PDF 변환 등 다양한 서버 사이드 문서 처리 기능으로 확장할 수 있습니다.