How to Work with Bibliography in .NET
This guide shows how to build the citation source data behind Word’s bibliography feature in Aspose.Words FOSS for .NET, using the Source, Contributor, Person, and Corporate classes in the Aspose.Words.Bibliography namespace. It covers creating source records, choosing the right source type, assigning individual and corporate contributors, and adding sources so CITATION and BIBLIOGRAPHY fields can resolve them.
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 a using Aspose.Words.Bibliography; directive for Source, SourceType, Contributor, ContributorCollection, Person, PersonCollection, and Corporate.
Step 3: Reach the Document’s Bibliography Data
Document.Bibliography returns a Bibliography instance. Its Sources property is an IList<Source> holding every source record available to the document, and BibliographyStyle records the citation style name – for example APA or MLA – that should be applied when a BIBLIOGRAPHY field is updated.
Step 4: Create a Source Record
Construct a Source with Source(tag, sourceType): Tag is the short identifier that FieldCitation.SourceTag and FieldBibliography.SourceTag match against later, and SourceType is an enum value identifying the kind of source – Book, BookSection, JournalArticle, ArticleInAPeriodical, ConferenceProceedings, Report, Patent, Case, InternetSite, DocumentFromInternetSite, Interview, Film, SoundRecording, Performance, Art, Electronic, or Misc. Give every Source a unique Tag – it is the only value the citation fields use to find the right record.
Step 5: Populate Fields for the Chosen Source Type
Beyond Title and ShortTitle, Source exposes dozens of category-specific fields – populate only the ones relevant to the chosen SourceType. Book sources use BookTitle, Edition, NumberVolumes, Volume, Pages, and ChapterNumber. Periodical sources use JournalName, PeriodicalTitle, PublicationTitle, and Issue. Web sources use InternetSiteTitle, Url, DayAccessed, MonthAccessed, and YearAccessed. Legal sources use CaseNumber, AbbreviatedCaseNumber, Court, and Reporter. Recording and broadcast sources use AlbumTitle, Broadcaster, BroadcastTitle, RecordingNumber, Medium, ProductionCompany, Distributor, Station, and Theater. General-purpose fields apply across most source types: Publisher, City, StateOrProvince, CountryOrRegion, Year, Month, Day, Comments, Guid, Doi, Version, RefOrder, and Lcid.
Step 6: Assign Individual Contributors
Source.Contributors returns a ContributorCollection with one property per contributor role – Author, Editor, Translator, Compiler, Composer, Conductor, Counsel, Director, Interviewee, Interviewer, Inventor, Performer, Producer, Writer, Artist, and BookAuthor – each typed as the abstract Contributor base class. Assign a Person (constructed from Last, First, Middle) to a role property for a single named individual.
Step 7: Assign Multiple or Corporate Contributors
When a role has more than one individual contributor, assign a PersonCollection instead of a single Person – PersonCollection also derives from Contributor and implements IEnumerable<Person>, with Add(), Remove(), RemoveAt(), Clear(), Contains(), and Count for managing its members. When the contributor is an organization rather than a person, assign a Corporate (constructed from its Name) to the role property instead. Person, PersonCollection, and Corporate all satisfy the same Contributor-typed role property, so choose whichever fits the source.
Step 8: Add the Source So Citation Fields Can Resolve It
Add every completed Source to Document.Bibliography.Sources before updating any CITATION or BIBLIOGRAPHY field that references it – a source that was constructed but never added has nothing for the referencing field to resolve to. Source records only supply data; they do not render citation or bibliography text themselves. Rendering happens through FieldCitation and FieldBibliography, covered in the links and references guide.
Common Issues and Fixes
A CITATION or BIBLIOGRAPHY field doesn’t resolve
The Source.Tag doesn’t exactly match the field’s SourceTag. Confirm the tags match, and that the Source was actually added to Document.Bibliography.Sources.
Wrong contributor type assigned to a role
A Person was assigned where multiple contributors exist, or vice versa. Use PersonCollection for multiple individuals in one role, Person for a single individual, and Corporate for an organization.
Source fields look inconsistent for its type
Fields for a different SourceType were populated – for example, web fields such as Url and DayAccessed set on a Book source. Populate only the fields relevant to the chosen SourceType.
A source with multiple authors only shows one name
A single Person was assigned to Author instead of a PersonCollection. Create a PersonCollection, add each Person with Add(), and assign the collection to the role property.
BibliographyStyle doesn’t match the citation format I expect
Bibliography.BibliographyStyle records which citation style name to apply – keep it consistent with how the document’s FieldCitation fields expect their output formatted.
Frequently Asked Questions
How do I add a book source with a single author?
Create a Source with SourceType.Book, set BookTitle, Publisher, Year, and related fields, then assign a Person to Source.Contributors.Author.
How do I add a source with multiple authors?
Assign a PersonCollection – populated with Person instances via Add() – to the relevant ContributorCollection role property, such as Author.
How do I cite an organization instead of an individual?
Assign a Corporate instance, constructed with the organization’s Name, to the ContributorCollection role property instead of a Person or PersonCollection.
Where do Source records actually appear in the rendered document?
They don’t render on their own – FieldCitation and FieldBibliography fields render content built from them, matched by SourceTag. See the links and references guide.
What identifies a Source record to the fields that cite it?
Source.Tag, set in the Source(tag, sourceType) constructor – FieldCitation.SourceTag and FieldBibliography.SourceTag match against this exact value.