How to Work with Word Links and References in .NET

This guide shows how to insert hyperlinks, cross-references to bookmarks, prompted-value fields, and citation fields in Aspose.Words FOSS for .NET, using FieldHyperlink, FieldRef, FieldPageRef, FieldCitation, and the other link and reference Field subclasses in the Aspose.Words.Fields namespace. It covers inserting a simple hyperlink, creating bookmarks and cross-referencing them, prompting for values during a field update, and citing bibliography sources.

Step-by-Step Guide

Step 1: Install the Package

Aspose.Words FOSS for .NET does not yet publish a NuGet package – build the library from source instead. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, then build Aspose.Words.sln in Release configuration with the .NET SDK and reference the resulting Aspose.Words assembly from your project. The library targets .NET Standard 2.0, so it runs on .NET Framework 4.6.2+ and .NET 6/8/10.

Step 2: Import Required Classes

Add a using Aspose.Words; directive for Document and DocumentBuilder, and a using Aspose.Words.Fields; directive for FieldHyperlink, FieldRef, FieldPageRef, FieldNoteRef, FieldStyleRef, FieldSet, FieldAsk, FieldFillIn, FieldCitation, FieldBibliography, and the other field classes this guide covers.

Step 3: Insert a Hyperlink

For a straightforward hyperlink, call DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark) – pass isBookmark: false for a URL target or true to link to a bookmark in the same document. Drop down to constructing a FieldHyperlink directly when properties the shortcut doesn’t expose are needed: Address and SubAddress hold the target URL or in-document location, ScreenTip sets the hover tooltip, OpenInNewWindow and IsImageMap are display flags, and Target names a browser frame.

Step 4: Create a Bookmark to Reference

Call DocumentBuilder.StartBookmark(bookmarkName) before the content the bookmark should cover, and DocumentBuilder.EndBookmark(bookmarkName) after it, using the same name for both calls. DocumentBuilder.MoveToBookmark(bookmarkName) moves the cursor to a bookmark that already exists – useful for navigating to a location before inserting a cross-reference field near it.

Step 5: Insert a Cross-Reference to That Bookmark

FieldRef (the REF field), FieldPageRef (PAGEREF), and FieldNoteRef (NOTEREF) each resolve to content at a named bookmark via their BookmarkName property. Set InsertHyperlink to make the reference clickable, and InsertRelativePosition to report a relative position (“above” / “below”) instead of the referenced text itself. FieldRef additionally supports paragraph-numbering options – InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator – and IncludeNoteOrComment. FieldStyleRef (STYLEREF) resolves to the nearest paragraph formatted with a given StyleName instead of a bookmark, with SearchFromBottom to search backward from the field’s position. FieldSet (SET) defines a bookmarked text value – BookmarkName and BookmarkText – that a REF field elsewhere can resolve.

Step 6: Prompt for a Value During an Update

FieldAsk (ASK) and FieldFillIn (FILLIN) request a value from whoever updates the field: set PromptText to the text shown to the user, DefaultResponse for a fallback value, and PromptOnceOnMailMerge to limit repeated prompting during a mail merge. FieldAsk additionally stores its answer at BookmarkName so other fields can reference it. For unattended field updates, supply answers programmatically rather than prompting interactively; see the fields guide for the callback interface that does this.

Step 7: Reference External or Linked Content

FieldDde (DDE) and FieldDdeAuto (DDEAUTO) link to content in another application via ProgId, SourceFullName, and SourceItem, with InsertAsText, InsertAsHtml, InsertAsPicture, InsertAsRtf, InsertAsUnicode, and InsertAsBitmap selecting the inserted representation, and AutoUpdate / IsLinked controlling refresh behavior. FieldLink (LINK) is the OLE-link equivalent, adding FormatUpdateType. FieldImport (IMPORT) and FieldIncludePicture (INCLUDEPICTURE) pull in an external graphic via SourceFullName and GraphicFilter. FieldInclude (INCLUDE) and FieldIncludeText (INCLUDETEXT) pull in external document content, with BookmarkName to scope the included range and LockFields to prevent it from being refreshed; FieldIncludeText additionally supports XML sources through Encoding, MimeType, NamespaceMappings, XPath, and XslTransformation.

Step 8: Reference Building Blocks and Glossary Entries

FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST), and FieldGlossary (GLOSSARY) all reference a named building-block entry through EntryName; FieldAutoTextList adds ListStyle and ScreenTip for its list-style presentation.

Step 9: Insert Citation and Bibliography Fields

FieldCitation (CITATION) and FieldBibliography (BIBLIOGRAPHY) render content sourced from the document’s bibliography data. Set FieldCitation.SourceTag (or the alternate AnotherSourceTag) to identify which source it cites, and use Prefix, Suffix, PageNumber, VolumeNumber, and the Suppress* flags (SuppressAuthor, SuppressTitle, SuppressYear) to control how the citation is formatted. FieldBibliography.SourceTag, FilterLanguageId, and FormatLanguageId control which sources appear in the rendered bibliography and in what language. These fields only render correctly once the matching Source records exist – see the bibliography guide for building those.

Common Issues and Fixes

REF, PAGEREF, or NOTEREF field shows an error result The BookmarkName it targets doesn’t exist in the document. Create the bookmark with DocumentBuilder.StartBookmark() / EndBookmark() before updating the field.

ASK or FILLIN field blocks an unattended update No callback is assigned to supply an answer programmatically. Assign the field-update callback described in the fields guide, or set DefaultResponse on the field so it has a fallback value.

CITATION or BIBLIOGRAPHY field renders empty The SourceTag doesn’t match any Source in the document’s bibliography data. Add the matching Source – see the bibliography guide.

DDE, DDEAUTO, or LINK field doesn’t refresh These fields reference an external OLE source that isn’t available outside the original Windows/OLE context. Treat the field’s stored result as the last-known value in that situation.

A hyperlink inserted with InsertHyperlink is missing a property I need DocumentBuilder.InsertHyperlink() is a shortcut that doesn’t expose every FieldHyperlink property. Construct or retrieve the FieldHyperlink directly to set properties such as ScreenTip or IsImageMap.

Frequently Asked Questions

What’s the difference between FieldRef and FieldStyleRef?

FieldRef resolves to content at a named bookmark (BookmarkName); FieldStyleRef instead resolves to the nearest paragraph formatted with a given StyleName, independent of bookmarks.

How do I insert a simple hyperlink without building a Field by hand?

Call DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark).

Are these link and reference field classes in a separate namespace from other fields?

No – FieldHyperlink, FieldRef, FieldCitation, and the rest of the classes covered here are ordinary Field subclasses in the Aspose.Words.Fields namespace, the same namespace used for every other field type.

How do citation fields relate to the bibliography data model?

FieldCitation and FieldBibliography render content by looking up SourceTag against the Source records described in the bibliography guide – these field classes handle rendering, while the Source and Contributor classes hold the underlying data.

How do I create a bookmark before referencing it?

Call DocumentBuilder.StartBookmark(bookmarkName) before the content, and DocumentBuilder.EndBookmark(bookmarkName) after it, using the same name for both calls.