IronWord와 Google Antigravity 사용 방법
필드 엔지니어들은 검사 보고서를 Word 파일로 제출하며, 포함된 사진은 증거입니다. 검토 페이지는 오류 없이 빌드되어도 사진을 누락하거나, 표 내의 이미지를 생략하거나, 잘못된 캡션을 할당하거나, 부정확한 사진 크기를 보고할 때 실패합니다. 빌드 로그에는 이러한 실패가 기록되지 않습니다.
Google Antigravity는 검토자가 페이지를 검사하는 방식으로 테스트할 수 있습니다. /browser 명령으로 시작된 샌드박스 브라우저 서브에이전트는 페이지를 열고, 파일 컨트롤에서 각각의 보고서를 선택하여 결과를 스크린샷으로 저장합니다. 서버에서, IronWord는 업로드된 DOCX 파일을 열고 Microsoft Office 설치 없이 ExtractImages을 통해 사진을 반환합니다. 아래의 검토 페이지는 두 도구로 빌드되어 사진 수, 캡션, 픽셀 크기가 알려진 여섯 가지 보고서에 대해 테스트되었습니다.
이 가이드는 .NET 코드를 작성해 Word 문서를 읽는 AI 에이전트를 가진 개발자를 위한 것입니다. AI 모델로 보고서를 직접 생성하는 것은 범위를 벗어납니다.
빠른 시작Blazor 프로젝트가 열리면 /plan 프롬프트에서 검토 페이지를 설명하세요.
/plan Add a report review page at /photos to this Blazor Web App on .NET 9.
The app uses the Interactive Server render mode.
Here's what the page needs:
- A reviewer picks a site inspection report (.docx) with InputFile.
- The server opens it with IronWord and calls ExtractImages.
- Add the IronWord package from NuGet, pinned to 2026.10.4. Its namespace is IronWord.
- Each photo appears as a thumbnail with its width and height in pixels and its image format.
- The page also shows how many photos the report holds.
- Link the page from NavMenu.
Read IRONWORD_LICENSE_KEY from the environment once at startup into IronWord.License.LicenseKey.
The app reads that variable itself.
Only check that it's set and how long it is.
Never print, log or store its value.
Don't list environment variables either.
Answer these in the Implementation Plan:
- which render mode the page gets
- how the upload stream reaches IronWord
- the size limit passed to OpenReadStream
You're done when dotnet build reports no errors.
성공적인 빌드는 계획에서 커버해야 할 세 가지 질문 중 어떤 것도 답변하지 않습니다. Microsoft의 렌더 모드 가이드는 페이지가 인터렉티브할 때를 설명하며, Blazor 파일 업로드 가이드는 업로드 처리와 크기 제한을 다룹니다.
에이전트에게 변수 이름을 제공하되, 값을 공유하지 마십시오. IronWord는 또한 appsettings.json에 있는 IronWord.LicenseKey 항목을 읽습니다. 이 파일은 실수로 커밋에 포함될 수 있습니다. 라이선스 키 가이드는 IronWord가 키를 확인하는 모든 위치를 나열합니다.
최소 워크플로우(5단계)
- NuGet에서 C# Word 라이브러리 다운로드
- 이미 localhost에서 페이지를 제공 중인 Blazor Web App으로 시작하세요
- 검토 페이지를 인터랙티브하게 만들고, 가장 큰 보고서보다 업로드 제한을 올리세요
- /browser로 모든 테스트 보고서를 업로드하고 나타내는 사진을 스크린샷으로 찍으세요
- 수량, 캡션, 픽셀 크기를 알려진 리스트와 비교한 후, API 레퍼런스에서 각각의 멤버를 확인하세요
Google Antigravity란 무엇이며 채팅 보조와 어떻게 다른가요?
Google의 개요에서 Antigravity 앱을 에이전트 팀을 시작하고 관리하고 검사하는 데스크톱 애플리케이션으로 설명합니다. 에이전트는 명령을 실행하고 파일을 읽고 쓰며, 샌드박스된 Chrome 브라우저를 제어합니다. 채팅 비서가 텍스트로 응답하는 동안 에이전트는 예를 들어 구현 계획과 같은 아티팩트를 반환합니다.
슬럽스쿼팅 공격에서는 누군가 AI 에이전트가 아직 제대로된 라이브러리 이름을 등록하지 않은 패키지 이름을 등록하여, 그 이름을 요청하는 에이전트가 공격자의 코드를 설치합니다. 패키지가 포함된 작업마다 IronWord 패키지를 명명하세요. 허브 AI 코딩 어시스턴트 안내서는 에이전트를 위한 IronWord의 문서 파일을 나열하며, 단일 프롬프트 수락 테스트를 포함합니다.
계획, 코드 변경, 워크스루에서 무엇을 확인해야 합니까?
Quickstart 프롬프트가 요청한 세 가지 답변 외에, 구현 계획은 사진 없는 보고서에 대해 생성된 메시지를 명시해야 합니다. 코드 변경 중에서는 픽셀 크기를 계산하는 줄을 찾아서 API 레퍼런스에서 각 IronWord 멤버를 확인하세요.
각 보고서는 단계별 가이드의 결과 테이블 옆에 자체 스크린샷이 필요합니다. Antigravity는 이미지 아티팩트로 스크린샷을 저장하며, 독자는 그 중 아무 곳에나 의견을 달 수 있습니다. 잘못된 사진 아래에 캡션이 있는 스크린샷에 대한 의견은 에이전트가 어떤 이미지를 수정해야 할 지 알려줍니다.
IronWord 검토 페이지를 실제 브라우저에서 테스트하는 방법은 무엇인가요?
/browser에 각 파일을 업로드함으로써만 채울 셀을 포함한 결과 테이블을 제공하세요.
/browser Start the site with dotnet run and open /photos.
Its http profile listens on http://localhost:5036.
Take each .docx file in TestData/reports through the page's file picker, one at a time:
1. Pick the file.
2. Wait for the photo list or an error message.
3. Take a screenshot.
TestData/reports/expected.csv lists each report's site photos in document order.
It gives their number, captions and pixel sizes, with | between entries.
Build a table in the Walkthrough with these columns:
- file
- bytes
- photos expected
- thumbnails shown
- pixel sizes expected
- pixel sizes shown
- pass or fail
For a failed row, quote the server log entry or browser console error behind it.
Do that before you change any code.
If neither recorded one, write that down.
After a fix, restart the app and put all six reports through the page again.
Stop the app when you finish.
여섯 가지 보고서는 사진 페이지가 처리해야 하는 레이아웃을 다룹니다. 하나는 PNG, JPEG, GIF를 포함하고, 하나는 사진을 표 셀에 저장합니다. 다른 하나는 페이지 헤더에 로고를 포함하고, 동일한 이미지를 두 번 배치하며, 사진이 없는 것이 하나 있으며, 네 개의 12 MP 사진이 포함된 7.7 MB 보고서가 있습니다.
누락되거나 잘못된 사진의 원인은 무엇인가요?
우리의 테스트에서는 실패한 모든 행이 세 가지 원인 중 하나로 인한 것이었습니다. 이들을 식별하기 위해 IronWord의 이미지 추출 안내서에서 추출 코드를 새로운 .NET 9 Blazor 프로젝트의 업로드 핸들러에 복사하고, 여섯 개의 보고서를 헤드리스 Chrome으로 처리했습니다.
| 페이지에 표시되는 내용 | 원인 | 수정 |
|---|---|---|
| 모든 보고서에 대해 출력 없음 | 정적 렌더링 | @rendermode InteractiveServer |
| 출력 없음, 그리고 서버 로그는 비어 있습니다 | 문서 생성자가 업로드 스트림을 동기적으로 읽어들입니다 | 업로드 스트림에서 LoadAsync |
| 최고 해상도 보고서에서만 발생하는 오류 | 512,000바이트 기본 업로드 제한 | 가장 큰 보고서보다 높은 제한 |
둘째 행은 진단하기 가장 어렵습니다. 생성자는 메시지 "동기적 읽기는 지원되지 않습니다."와 함께 NotSupportedException을 던졌습니다. 예외는 핸들러가 이를 캡처하고 로그할 때만 드러났습니다.
Antigravity가 작업할 수 있는 프로젝트를 어떻게 설정하나요?
Antigravity에 이미 빌드되어 페이지를 제공하는 저장소를 제공하세요. 테스트 프로젝트는 dotnet new blazor -int Server -f net9.0에서 가져왔으며, 어떤 프롬프트도 실행되기 전에 오류 0으로 빌드되었습니다. 템플릿은 Properties/launchSettings.json의 http 프로파일에 임의의 포트를 쓰므로, 그 URL을 /browser 프롬프트에 복사하세요.
다음 작업은 패키지 및 라이선스 키를 검사합니다.
Which IronWord version does this project reference? Quote its PackageReference line.
Then point me to the line that applies the license key.
Check the project against these key rules:
- The key reaches the app only through IRONWORD_LICENSE_KEY at startup.
- Neither appsettings.json nor appsettings.Development.json has an IronWord.LicenseKey entry.
- Properties/launchSettings.json doesn't carry the key.
- A missing variable at startup gets one logged warning that names it and shows no value.
Edit Program.cs only if that warning doesn't exist yet.
Leave every other file as it is.
Tell me which rules pass and which fail.
보고된 버전을 이후 작업에서 인용하세요. IronWord 2026.10.4는 모든 보고서를 열고 아주 모든 사진을 라이선스 키 없이 추출했습니다. 저장은 "프로덕션 라이선스 필요"라는 내용의 LicensingException을 던졌습니다. 따라서 누락된 키는 처음으로 파일을 쓸 때만 드러나며, 이 읽기 전용 페이지는 절대 쓰지 않습니다.
페이지의 규칙을 추후 작업에 어떻게 적용할까요?
모든 여섯 행이 통과한 후, 세션이 결정한 바를 기록하세요. Antigravity의 규칙 문서는 에이전트가 파일을 읽거나 편집할 때마다 해당 파일과 워크스페이스 루트 사이에 발견된 모든 폴더에서 GEMINI.md 또는 AGENTS.md를 로드한다고 말합니다. /learn은 세션의 피드백을 지속 가능한 프로젝트 규칙으로 변환합니다.
/learn Create AGENTS.md at the root of the repository and record what this session settled.
Put the notes under the heading "Inspection report photos". They should cover:
- the render mode the /photos page needs
- the upload limit, with the reason for its value
- how the upload reaches IronWord without a synchronous read
- where a photo's pixel size comes from
- that IRONWORD_LICENSE_KEY stays out of every file
- that no page change is done until all six reports in TestData/reports pass the /browser table
파일이 존재하면, 렌더 모드와 업로드 제한은 모든 작업이 읽는 한 위치에 기록됩니다. 에이전트는 해당 파일을 자동으로 업데이트하지 않습니다. 값을 변경하는 동일 작업에서 업데이트를 요청하세요.
IronWord로 업로드된 보고서를 어떻게 로드합니까?
결과와 증거를 명시하고 에이전트가 코드를 구조화할 수 있게 하세요.
/plan Write the Implementation Plan Artifact before you edit anything.
Move the IronWord code out of the page into Services/ReportPhotoService.cs.
Register it as a singleton.
The service works like this:
- It opens the upload with WordDocument.LoadAsync, straight from OpenReadStream with a 30 MB limit.
- It checks the file's Size first and turns away anything larger before it opens a stream.
- A refused file gets a clear message that the page shows.
- A second public method takes an already loaded WordDocument.
- Tests can call that method without a browser.
For each photo, the service returns:
- the pixel size
- the size the photo is placed at in the report, in inches
- the format
- a JPEG thumbnail no wider than 320 pixels
- the caption
A caption is the first paragraph with text after the photo's own paragraph.
For a photo inside a table cell, it's the text of the cell directly below.
Show each caption under its thumbnail.
Then repeat the /browser table with a captions column checked against expected.csv.
이 예시와 유사한 서비스를 예상하세요. IronWord 2026.10.4와 함께 컴파일되며, 이를 사용하는 보정 테스트 페이지는 모든 여섯 보고서에 대해 사진 수, 캡션 및 픽셀 크기를 정확히 나열했습니다.
using IronSoftware.Drawing;
using IronWord;
using IronWord.Models;
using Microsoft.AspNetCore.Components.Forms;
public sealed record ReportPhoto(int PixelWidth, int PixelHeight, double WidthPoints, double HeightPoints, string Format, string Caption, string ThumbnailDataUrl);
public sealed class ReportPhotoService
{
public const long MaxUploadBytes = 30 * 1024 * 1024;
public async Task<List<ReportPhoto>> ReadAsync(IBrowserFile file)
{
if (file.Size > MaxUploadBytes)
throw new IOException($"{file.Name} is {file.Size:N0} bytes, over the {MaxUploadBytes:N0} byte limit.");
await using var upload = file.OpenReadStream(MaxUploadBytes);
var doc = await WordDocument.LoadAsync(upload);
return Read(doc);
}
public static List<ReportPhoto> Read(WordDocument doc)
{
var photos = new List<ReportPhoto>();
var body = doc.Paragraphs.Where(p => p.Parent is DocumentSection).ToList();
for (int i = 0; i < body.Count; i++)
{
foreach (var img in body[i].ExtractImages())
{
var caption = body.Skip(i + 1).Select(p => p.ExtractText().Trim()).FirstOrDefault(t => t.Length > 0) ?? "";
photos.Add(Make(img, caption));
}
}
foreach (var table in doc.Tables)
for (int r = 0; r < table.Rows.Count; r++)
for (int c = 0; c < table.Rows[r].Cells.Count; c++)
foreach (var img in ((TableCell)table.Rows[r].Cells[c]).ExtractImages())
{
var caption = r + 1 < table.Rows.Count && c < table.Rows[r + 1].Cells.Count
? ((TableCell)table.Rows[r + 1].Cells[c]).ExtractText().Trim() : "";
photos.Add(Make(img, caption));
}
return photos;
}
static ReportPhoto Make(ImageContent img, string caption)
{
var bmp = (AnyBitmap)img.Image;
int tw = Math.Min(320, bmp.Width);
int th = Math.Max(1, bmp.Height * tw / bmp.Width);
using var thumb = new AnyBitmap(bmp, tw, th);
var jpg = thumb.ExportBytes(AnyBitmap.ImageFormat.Jpeg, 80);
return new ReportPhoto(bmp.Width, bmp.Height, img.Width, img.Height, img.Type.ToString(), caption,
"data:image/jpeg;base64," + Convert.ToBase64String(jpg));
}
}
크기 확인은 브라우저에서 보고된 값을 사용하므로, 치수 초과 파일은 업로드 스트림 열기 전 실패합니다. Microsoft의 업로드 가이드는 이 클라이언트 제공 값에만 의존하는 것을 지양하며, OpenReadStream에 설정된 제한이 실제 제한을 적용합니다. 최대 해상도 보고서를 읽는 데 두 번의 보정 실행에서 각각 1,118 ms와 1,280 ms가 걸렸습니다. 대량의 데이터 전송을 피하기 위해 서비스는 브라우저로 풀 사이즈 이미지를 보내는 대신 스케일된 썸네일을 생성합니다.
IronWord는 문서에서 어떤 이미지를 추출합니까?
ExtractImages 메소드는 문서 본문과 테이블 셀에 위치한 사진을 반환합니다. 페이지 헤더의 로고는 생략하여 편지글은 사이트 사진으로 계산하지 않습니다. 사진이 여러 번 등장하면, 각각의 배치에 대해 각기 다른 크기로 한 번씩 반환됩니다.
각 결과에는 포인트 단위로 너비와 높이가 포함되어 있습니다. 예를 들어, 3인치 너비의 사진은 해상도와 관계없이 216포인트로 보고됩니다. 샘플 서비스는 이러한 포인트 값을 유지합니다. 인치로 변환하려면 72로 나누거나 GetWidth(MeasurementUnit.Inch)을 사용하세요, 에이전트가 시연한 것처럼. 픽셀 크기는 디코딩된 이미지에서 얻어지며, Image 속성을 AnyBitmap로 캐스팅하거나 ImageData의 Base64 문자열을 디코딩하여 얻어집니다.
단락 목록에는 테이블 셀의 단락이 읽기 순서로 포함되어 있으므로 텍스트가 있는 다음 단락을 선택하면 첫 번째 테이블 사진의 캡션이 두 번째 테이블 사진으로 할당됩니다. 문서의 ExtractText는 테이블 텍스트도 생략하므로, 출력에는 테이블 캡션이 포함되지 않습니다.
언제 한 에이전트 이상을 파견해야 하나요?
검사 작업을 두 개의 에이전트로 나누세요. 하나는 코드에서 서비스를 테스트합니다. 다른 하나는 리뷰어의 업로드를 브라우저에서 재생합니다.
Agent A: add an xUnit project named InspectionPhotos.Tests.
Its tests take each report in TestData/reports through these steps:
1. Load the report from disk with WordDocument.
2. Pass it through the extraction code in ReportPhotoService.
3. Assert the photo count, pixel sizes and captions that expected.csv lists, in document order.
Add one more test proving a file above the upload limit is refused before IronWord opens it.
expected.csv quotes any field that holds a comma, so parse it as CSV.
The web project is at the repository root, so keep the test folder out of its compile items.
Run the tests with dotnet test InspectionPhotos.Tests.
Agent B: wait until Agent A's tests are green on the current code.
Then put the six reports through /photos with /browser.
Attach one screenshot per report to the Walkthrough.
Note there that the tests ran first.
디스크에서 보고서를 여는 테스트에는 브라우저나 실행 중인 애플리케이션이 필요하지 않으므로 /browser 패스를 확인하기 전에 캡션 회귀를 감지합니다.
페이지를 Linux 컨테이너에 배포하는 방법은 무엇인가요?
관리되는 어셈블리 외에도, IronWord 2026.10.4는 Windows(x64 및 x86), linux-x64 및 macOS용으로 빌드된 네이티브 레이아웃 라이브러리를 포함하고 있습니다.
This page will run in a linux-x64 container based on mcr.microsoft.com/dotnet/aspnet:9.0.
Leave the C# untouched.
Docker is missing on this machine, so don't run docker build.
Work through these steps:
1. Write a Dockerfile whose build stage publishes a linux-x64 build.
2. Have the image take IRONWORD_LICENSE_KEY from the container environment when it starts.
3. Run dotnet publish -c Release -r linux-x64 --self-contained false -o out/linux.
Then list every native library (.so) in out/linux with the NuGet package that supplied it.
If there's none, say so.
네이티브 파일을 나열하는 데 Docker가 필요하지 않은데, Windows의 배포 폴더에도 이미지를 받을 동일한 파일이 있기 때문입니다. linux-x64용으로 보정 앱을 게시한 결과 네이티브 파일 하나, libLayoutEngineInterop.so(8,303,240 바이트)가 만들어졌습니다. 해당 파일은 glibc에만 연결되며, 패키지에 musl 또는 linux-arm64 빌드가 없으므로, 이 릴리스는 Alpine 또는 ARM64 Linux 이미지에는 네이티브 라이브러리가 없습니다. Windows에서 사진을 로드하고 추출하는 것은 네이티브 라이브러리를 로드하지 않았습니다. IronWord의 Docker 가이드는 Ubuntu, Debian, 또는 RHEL 이미지를 사용하도록 권장합니다.
실제 실행에서 프롬프트가 무엇을 생성했습니까?
한 Antigravity CLI 세션은 모든 일곱 프롬프트를 무인으로 실행하고 모든 권한 프롬프트를 건너뛰었습니다. 앱은 IRONWORD_LICENSE_KEY에서만 라이선스 키를 읽었습니다. 첫 번째 프롬프트의 코드와 최종 코드에서 각각 무헤드 Chrome에서 각 보고서를 두 번 업로드했습니다.
- – 두 번의 Chrome 검사에서 모든 여섯 보고서의 사진 수와 픽셀 크기는 정확했습니다.
- 첫 번째 프롬프트 이후에는 없다고 요청한 캡션이 없었으나, 최종 애플리케이션에서는 12개 중 12개가 올바르게 나왔습니다.
- 애플리케이션과 테스트 프로젝트의 릴리스 빌드에서 경고와 오류가 0으로 보고되었습니다.
- 모든 일곱 xUnit 테스트가 통과되었습니다.
- linux-x64 출판에는 네이티브 라이브러리 하나가 포함되었습니다.
- 세 번의 브라우저 패스에서 파일 선택기를 통해 여섯 가지 모든 보고서를 처리했습니다.
- 일부 단계는 페이지와 달리 작동했습니다. Quickstart 프롬프트는 이미 30 MB 한도를 설정하고 각 업로드를 메모리로 복사했으므로, 위의 세 가지 원인은 나타나지 않았습니다. 각 /plan 프롬프트는 승인 도착 때까지 계획 후 멈췄습니다. 에이전트 A와 에이전트 B는 같은 대화의 한 턴에서 실행되었습니다. 썸네일은 IronWord의 의존성인 SixLabors.ImageSharp으로 리사이징되었습니다. 에이전트는 첫 번째 브라우저 패스의 스크린샷과 out/linux 게시 폴더를 커밋했습니다.
- /learn은 AGENTS.md를 작성하지 않았습니다. 그의 아티팩트는 모든 여섯 포인트를 나열하고 먼저 확인을 요청했습니다.
ChatGPT Codex guide는 동시성 제한 하에 Word 문서의 전체 폴더를 병렬로 처리하며, 이 페이지는 한 번에 하나의 업로드를 처리합니다. Claude Code guide는 파일 변경 전에 계획 모드에서 설계를 승인하며, 계획 우선 프롬프트가 여기서 이를 수행합니다.
이 실행에 대한 Antigravity CLI 버전, 모델, 지속 시간 및 테스트 기계는 허브의 실행 기록에 있습니다.
문제 해결
- 이 페이지에서 사용하는 추출 방법에 대한 DOCX에서 이미지 추출
- 캡션이나 테이블 텍스트가 누락된 경우에는 DOCX에서 텍스트 추출
License.IsLicensed로 키가 적용되었는지 확인한 후의 IronWord 라이선스 키- Ubuntu, Debian 및 RHEL에 대한 Dockerfile 예제를 위한 Docker에서의 IronWord 설정
- 프로젝트가 OpenXML SDK도 참조할 때 DocumentFormat.OpenXml과 함께 IronWord
질문?
질문이 있으시면 support@ironsoftware.com으로 문의하세요.
커티스 차우는 칼턴 대학교에서 컴퓨터 과학 학사 학위를 취득했으며, Node.js, TypeScript, JavaScript, React를 전문으로 하는 프론트엔드 개발자입니다. 직관적이고 미적으로 뛰어난 사용자 인터페이스를 만드는 데 열정을 가진 그는 최신 프레임워크를 활용하고, 잘 구성되고 시각적으로 매력적인 매뉴얼을 제작하는 것을 즐깁니다.