Wie verwendet man IronWord mit Google Antigravity
Feldingenieure reichen Inspektionsberichte als Word-Dateien ein, und die eingebetteten Fotos sind der Beweis. Eine Überprüfungsseite, die ohne Fehler erstellt wird, schlägt dennoch fehl, wenn sie Fotos fallen lässt, Bilder in Tabellen weglässt, falsche Bildunterschriften zuweist oder ungenaue Fotogrößen berichtet. Ein Erstellungsprotokoll zeichnet keine dieser Fehler auf.
Google Antigravity kann die Seite testen, wie es ein Prüfer tut. Ein sandboxed Browser-Subagent, gestartet mit dem /browser-Befehl, öffnet die Seite, wählt jeden Bericht in der Dateisteuerung aus und macht einen Screenshot des Ergebnisses. Auf dem Server öffnet IronWord die hochgeladenen DOCX-Dateien und gibt deren Fotos über ExtractImages zurück, ohne Microsoft Office-Installation. Die Überprüfungsseite unten wurde mit beiden Tools erstellt und gegen sechs Berichte mit bekannten Fotoanzahlen, Bildunterschriften und Pixelgrößen getestet.
Der Leitfaden richtet sich an Entwickler, die AI-Agenten .NET-Code schreiben lassen, der Word-Dokumente liest. Das Generieren der Berichte durch ein AI-Modell fällt nicht in den Bereich.
SchnellstartBeschreiben Sie die Überprüfungsseite in einem /plan-Befehl, sobald Antigravity das Blazor-Projekt geöffnet hat.
/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.
Ein erfolgreicher Build beantwortet keine der drei Fragen, die der Plan abdecken muss. Microsofts Anleitung zu Rendermodi erklärt, wann eine Seite interaktiv ist, und die Blazor-Dateiupload-Anleitung behandelt das Upload-Handling und Größenbeschränkungen.
Geben Sie dem Agenten den Variablennamen, aber teilen Sie nicht seinen Wert. IronWord liest auch einen IronWord.LicenseKey-Eintrag in appsettings.json, eine Datei, die ein Commit fälschlicherweise enthalten kann. Der Lizenzschlüssel-Leitfaden listet alle Orte auf, an denen IronWord nach dem Schlüssel sucht.
Minimaler Arbeitsablauf (5 Schritte)
- Laden Sie die C# Word-Bibliothek von NuGet herunter
- Beginnen Sie mit einer Blazor-Web-App, die bereits Seiten auf localhost bereitstellt
- Machen Sie die Überprüfungsseite interaktiv und erhöhen Sie das Upload-Limit über Ihren größten Bericht
- Lassen Sie /browser jeden Testbericht hochladen und die angezeigten Fotos screenshoten
- Vergleichen Sie Zählungen, Bildunterschriften und Pixelgrößen mit einer bekannten Liste und bestätigen Sie jedes Mitglied in der API-Referenz
Was ist Google Antigravity und wie unterscheidet es sich von einem Chat-Assistenten?
Googles Übersicht beschreibt die Antigravity-App als Desktop-Anwendung, die Teams von Agenten startet, orchestriert und inspiziert. Ein Agent führt Befehle aus, liest und schreibt Dateien und steuert einen sandboxed Chrome-Browser. Ein Chat-Assistent antwortet mit Text, während ein Agent Artefakte zurückgibt, z.B. einen Implementierungsplan.
In einem slopsquatting-Angriff registriert jemand ein Paket unter einem Namen, den AI-Agenten für nie veröffentlichte Bibliotheken erzeugen, und ein Agent, der diesen Namen anfordert, installiert den Code des Angreifers. Bennen Sie das IronWord-Paket in jeder Aufgabe, die Pakete beinhaltet. Der Hub AI-Coding-Assistenten-Leitfaden listet die Dokumentationsdateien von IronWord für Agenten auf und enthält einen Ein-Prompt-Akzeptanztest.
Was sollten Sie im Plan, den Codeänderungen und der Anleitung überprüfen?
Über die drei Antworten hinaus, die der Quickstart-Befehl anfordert, sollte der Implementierungsplan die Nachricht angeben, die für einen Bericht ohne Fotos erzeugt wurde. Unter den Codeänderungen finden Sie die Zeile, die die Pixelgröße berechnet, und überprüfen Sie jedes IronWord-Mitglied anhand der API-Referenz.
Jeder Bericht benötigt seinen eigenen Screenshot im Durchlauf, neben der Ergebnistabelle. Antigravity speichert Screenshots als Bildartefakte, und ein Leser kann auf jedes kommentieren. Ein Kommentar zu einem Screenshot, der eine Bildunterschrift unter dem falschen Foto zeigt, teilt dem Agenten mit, welches Bild er reparieren soll.
Wie testen Sie die IronWord-Überprüfungsseite in einem echten Browser?
Geben Sie /browser eine Ergebnistabelle, deren Zellen es nur füllt, indem es jede Datei hochlädt.
/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.
Die sechs Berichte decken die Layouts ab, die eine Fotoseite verarbeiten muss. Einer enthält ein PNG, ein JPEG und ein GIF, und einer speichert Fotos in Tabellenzellen. Ein anderer enthält ein Logo im Seitenkopf, einer platziert dasselbe Bild zweimal, einer enthält keine Fotos, und einer ist ein 7,7 MB-Bericht mit vier 12 MP-Fotos.
Was verursacht fehlende oder falsche Fotos?
In unseren Tests resultierte jede fehlgeschlagene Zeile aus einer von drei Ursachen. Um sie zu identifizieren, wurde der Extraktionscode aus dem Extraktionsleitfaden von IronWord in einen Upload-Handler in einem neuen .NET 9 Blazor-Projekt kopiert, und die sechs Berichte wurden durch kopfloses Chrome verarbeitet.
| Was die Seite anzeigt | Ursache | Korrektur |
|---|---|---|
| Kein Output für irgendeinen Bericht | Statische Darstellung | @rendermode InteractiveServer |
| Kein Output, und das Serverprotokoll bleibt leer | Der Dokumentenkonstruktor liest den Upload-Stream synchron | LoadAsync auf dem Upload-Stream |
| Ein Fehler nur für den Bericht mit voller Auflösung | Das Standard-Upload-Limit von 512.000 Byte | Ein Limit über dem größten Bericht |
Die zweite Zeile ist am schwierigsten zu diagnostizieren. Der Konstruktor warf NotSupportedException mit der Nachricht "Synchronous reads are not supported." Die Ausnahme wurde erst sichtbar, als der Handler sie abfing und protokollierte.
Wie richtet man ein Projekt ein, in dem Antigravity arbeiten kann?
Geben Sie Antigravity ein Repository, das bereits eine Seite erstellt und bereitstellt. Das Testprojekt kam aus dotnet new blazor -int Server -f net9.0 und wurde mit 0 Fehlern erstellt, bevor irgendein Befehl lief. Die Vorlage schreibt einen Zufallshafen in das HTTP-Profil von Properties/launchSettings.json, also kopieren Sie diese URL in den /browser-Befehl.
Die nächste Aufgabe überprüft das Paket und den Lizenzschlüssel.
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.
Zitieren Sie die gemeldete Version in späteren Aufgaben. IronWord 2026.10.4 öffnete jeden Bericht und extrahierte jedes Foto ohne jeden Lizenzschlüssel. Das Speichern warf eine LicensingException, die "Production License Required" las. Ein fehlender Schlüssel wird daher erst dann offensichtlich, wenn die App zum ersten Mal eine Datei schreibt, was diese schreibgeschützte Seite nie tut.
Wie wenden Sie die Regeln der Seite auf spätere Aufgaben an?
Nachdem alle sechs Zeilen bestanden wurden, zeichnen Sie auf, was die Sitzung entschieden hat. Antigravitys Regeldokumentation besagt, dass jedes Mal, wenn der Agent eine Datei liest oder bearbeitet, er jede GEMINI.md oder AGENTS.md lädt, die er in jedem Ordner zwischen dieser Datei und dem Root des Arbeitsraums findet. /learn wandelt Feedback aus der Sitzung in permanente Projektrichtlinien um.
/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
Sobald die Datei existiert, werden der Rendermodus und das Upload-Limit an einem Ort aufgezeichnet, den jede Aufgabe liest. Der Agent aktualisiert diese Datei nicht automatisch. Fordern Sie das Update in derselben Aufgabe an, die den Wert ändert.
Wie laden Sie einen hochgeladenen Bericht mit IronWord?
Geben Sie das Ergebnis und den Beweis an und erlauben Sie dem Agenten, den Code zu strukturieren.
/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.
Erwarten Sie einen Dienst ähnlich diesem Beispiel. Es wird mit IronWord 2026.10.4 kompiliert, und die Kalibrierungstestseite, die es verwendet, listete korrekt die Fotoanzahl, Bildunterschriften und Pixelgrößen für alle sechs Berichte auf.
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));
}
}
Die Größenkontrolle verwendet den vom Browser gemeldeten Wert, sodass eine übergroße Datei fehlschlägt, bevor der Upload-Stream geöffnet wird. Microsofts Upload-Leitfaden rät davon ab, sich ausschließlich auf diesen vom Client bereitgestellten Wert zu verlassen, und das in OpenReadStream gesetzte Limit erzwingt die tatsächliche Obergrenze. Das Lesen des Berichts mit voller Auflösung dauerte 1.118 ms und 1.280 ms in zwei Kalibrierläufen. Um große Datenübertragungen zu vermeiden, generiert der Dienst skalierte Thumbnails, anstatt Vollbilder an den Browser zu senden.
Welche Bilder extrahiert IronWord aus einem Dokument?
Die ExtractImages-Methode gibt Fotos zurück, die sich im Dokumentkörper und in Tabellenzellen befinden. Es überspringt das Logo im Seitenkopf, sodass ein Briefkopf nicht als Seite-Foto zählt. Erscheint ein Foto mehrfach, wird es für jede Platzierung einmal zurückgegeben, jeweils mit eigener Größe.
Jedes Ergebnis enthält seine Breite und Höhe in Punkten. Zum Beispiel wird ein 3-Zoll-breites Foto als 216 Punkte berichtet, unabhängig von der Auflösung. Der Beispieldienst behält diese Punktwerte bei. Zum Umrechnen in Zoll, teilen Sie durch 72 oder verwenden Sie GetWidth(MeasurementUnit.Inch), wie vom Agenten demonstriert. Die Pixelgröße wird aus dem dekodierten Bild erhalten, entweder durch casten der Image-Eigenschaft in AnyBitmap oder durch Dekodierung der Base64-Zeichenkette in ImageData.
Die Absatzliste enthält Absätze innerhalb von Tabellenzellen in Leserichtung, sodass die Auswahl des nächsten Absatzes mit Text die Bildunterschrift des ersten Fotos der Bildunterschrift des zweiten Tabellenfotos zuweist. Die ExtractText des Dokuments lässt auch Tabellen text aus, sodass seine Ausgabe keine Tabellenüberschriften enthält.
Wann sollten Sie mehr als einen Agenten entsenden?
Teilen Sie die Überprüfungen zwischen zwei Agenten auf. Einer testet den Dienst im Code. Der andere wiederholt die Uploads des Prüfers im Browser.
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.
Tests, die Berichte von der Festplatte öffnen, benötigen weder einen Browser noch eine laufende Anwendung, sodass sie eine Bildunterschriftregression vor einem Browser-Durchlauf erfassen.
Wie verteilen Sie die Seite in einem Linux-Container?
Neben seinen verwalteten Assemblies enthält IronWord 2026.10.4 eine native Layout-Bibliothek, die für Windows (x64 und x86), linux-x64 und macOS erstellt wurde.
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 ist nicht erforderlich, um die nativen Dateien aufzulisten, da der Veröffentlichung-Ordner unter Windows dieselben Dateien enthält, die das Image erhält. Das Veröffentlichen der Kalibrierungs-App für linux-x64 erzeugte eine native Datei, libLayoutEngineInterop.so (8.303.240 Byte). Diese Datei verlinkt nur gegen glibc, und das Paket hat keinen musl- oder linux-arm64-Build, sodass diese Version keine native Bibliothek für Alpine- oder ARM64-Linux-Images hat. Unter Windows lud das Laden und Extrahieren von Fotos nicht die native Bibliothek. Der Docker-Leitfaden von IronWord empfiehlt die Verwendung von Ubuntu-, Debian- oder RHEL-Images.
Was haben die Aufforderungen in einem realen Lauf erzeugt?
Eine CLI-Sitzung von Antigravity lief alle sieben Prompts unbeaufsichtigt und übersprang jede Berechtigungsaufforderung. Die App las den Lizenzschlüssel nur aus IRONWORD_LICENSE_KEY. Wir luden jeden Bericht in kopflosem Chrome zweimal hoch, einmal auf dem Code aus dem ersten Prompt und einmal auf dem letzten Code.
- Fotobeschreibungen und Pixelgrößen waren für alle sechs Berichte in beiden Chrome-Checks korrekt.
- Bildunterschriften gingen von keiner nach dem ersten Prompt, der keine verlangte, zu 12 von 12 korrekten in der endgültigen Anwendung.
- Release-Builds der Anwendung und des Testprojekts berichteten 0 Warnungen und 0 Fehler.
- Alle sieben xUnit-Tests bestanden.
- Das linux-x64 veröffentlicht umfasste eine native Bibliothek.
- Jede der drei Browser-Durchläufe verarbeitete alle sechs Berichte durch den Datei-Picker.
- Einige Schritte liefen anders als die Seite. Der Quickstart-Befehl stellte bereits das 30-MB-Limit ein und kopierte jeden Upload in den Speicher, sodass keine der oben genannten drei Ursachen auftrat. Jeder /plan-Prompt hielt an, nachdem sein Plan eingegangen war, bis eine Genehmigung eintraf. Agent A und Agent B liefen in einer Runde desselben Gesprächs. Thumbnails wurden mit SixLabors.ImageSharp, einer übertragenden IronWord-Abhängigkeit, skaliert. Der Agent verpfändete die Screenshots des ersten Browser-Durchlaufs und den out/linux-Veröffentlichungsordner.
- /learn schrieb keine AGENTS.md. Sein Artefakt listete alle sechs Punkte auf und bat zuerst um Bestätigung.
Der ChatGPT-Codex-Leitfaden verarbeitet einen ganzen Ordner mit Word-Dokumenten parallel unter einem Nebenläufigkeitslimit, wobei diese Seite einen Upload nach dem anderen behandelt. Der Claude-Code-Leitfaden genehmigt ein Design im Plan-Modus, bevor Dateien geändert werden, so wie die Plan-First-Prompts hier.
Die Antigravity-CLI-Version, das Modell, die Dauer und die Testmaschine für diesen Lauf befinden sich im Hub der Laufdatei.
Fehlerbehebung
- Bilder aus DOCX extrahieren für die hier verwendete Extraktionsmethode
- Text aus DOCX extrahieren, wenn Bildunterschriften oder Tabellentext fehlen
- IronWord-Lizenzschlüssel, um mit
License.IsLicensedzu bestätigen, dass der Schlüssel angewendet wurde - Einrichten von IronWord in Docker für Dockerfile-Beispiele auf Ubuntu, Debian und RHEL
- IronWord mit DocumentFormat.OpenXml, wenn das Projekt auch das OpenXML SDK referenziert
Fragen?
Wenn Sie Fragen haben, wenden Sie sich an support@ironsoftware.com.
Curtis Chau hat einen Bachelor-Abschluss in Informatik von der Carleton University und ist spezialisiert auf Frontend-Entwicklung mit Expertise in Node.js, TypeScript, JavaScript und React. Leidenschaftlich widmet er sich der Erstellung intuitiver und ästhetisch ansprechender Benutzerschnittstellen und arbeitet gerne mit modernen Frameworks sowie der Erstellung gut strukturierter, optisch ansprechender Handbücher.