AnkiIO.AnkiNote Class Reference

Stores one fact or item of knowledge and owns the cards generated from it. More...

Public Member Functions
	AnkiNote (AnkiNoteType noteType, IReadOnlyDictionary< string, string > fields, IEnumerable< string >? tags=null, long? id=null, string? guid=null)
	Initializes a detached note while preserving its stable identity.
void	SetField (string name, string value)
	Replaces a defined field value.
void	AddTag (string tag)
	Adds a note-level search/organization tag if it is not already present.
bool	RemoveTag (string tag)
	Removes one exact, case-sensitive note tag.

Properties
long	Id [get]
	Gets the persisted numeric identity shared by every card generated from this note.
string	Guid [get]
	Gets Anki's stable text identity used to match the same note during import/update workflows.
AnkiNoteType	NoteType [get]
	Gets the shared model that defines field order, rendering templates, CSS, and card generation.
IReadOnlyDictionary< string, string >	Fields [get]
	Gets this note's values keyed by the exact names in AnkiNoteType.Fields.
IReadOnlyCollection< string >	Tags [get]
	Gets note-level labels used for organization and search in Anki.
IReadOnlyList< AnkiCard >	Cards [get]
	Gets the study prompts currently generated for this note.

Detailed Description

Stores one fact or item of knowledge and owns the cards generated from it.

Notes and cards are deliberately different: editing a note's field changes what all of its sibling cards render, while scheduling and color flags remain card-specific. Create ordinary notes through AnkiDeck.AddNote or the Basic/Cloze helpers so the note is attached and cards are generated. The public constructor exists for adapters and creates a detached note with an empty Cards collection.

Field values may contain HTML and Anki template/media references; AnkiIO stores them verbatim and does not sanitize or render them. Instances are mutable and not safe for concurrent mutation.

var deck = new AnkiDeck("German");
var note = deck.AddBasicAndReversedNote("gehen", "to go", tags: ["verb"]);
note.SetField("Back", "to go; to walk"); // both sibling cards use the new value
note.AddTag("a1");

Definition at line 26 of file AnkiNote.cs.

Constructor & Destructor Documentation

AnkiNote()

AnkiIO.AnkiNote.AnkiNote ( AnkiNoteType noteType, IReadOnlyDictionary< string, string > fields, IEnumerable< string >? tags = null, long? id = null, string? guid = null )

inline

Initializes a detached note while preserving its stable identity.

Parameters

noteType	A completely configured note type, retained by reference and frozen on success.
fields	Field values keyed by exact, ordinal field name. Missing defined fields become empty strings.
tags	Optional non-empty tags without whitespace; duplicates are collapsed using ordinal comparison. The whitespace restriction ensures tags can be represented losslessly by legacy Anki package storage.
id	An optional stable numeric note identifier, or null to generate one.
guid	An optional stable Anki import GUID, or null or blank to generate one.

This constructor does not generate cards or attach the note to a deck. It is useful when an importer will restore cards separately. After all arguments have been validated it freezes noteType against later field, template, and CSS changes. Prefer AnkiDeck.AddNote for authored decks.

Exceptions

ArgumentNullException	noteType or fields is null.
ArgumentException	fields contains a name absent from noteType , or tags contains a blank or whitespace-containing value.

Definition at line 55 of file AnkiNote.cs.

Member Function Documentation

AddTag()

void AnkiIO.AnkiNote.AddTag ( string tag )

inline

Adds a note-level search/organization tag if it is not already present.

Parameters

tag	The case-sensitive tag text without whitespace. Existing identical tags are left unchanged.

Exceptions

ArgumentException	tag is blank or contains whitespace.
ArgumentNullException	tag is null.

Definition at line 169 of file AnkiNote.cs.

RemoveTag()

bool AnkiIO.AnkiNote.RemoveTag ( string tag )

inline

Removes one exact, case-sensitive note tag.

Parameters

tag	The exact, case-sensitive tag to remove.

Returns

true when the tag existed and was removed; otherwise, false.

Definition at line 178 of file AnkiNote.cs.

SetField()

void AnkiIO.AnkiNote.SetField ( string name, string value )

inline

Replaces a defined field value.

Parameters

name	The exact, case-sensitive field name.
value	The replacement value, including any Anki HTML or media/template markup, stored verbatim.

For standard notes, every sibling card immediately renders the new value and card identity/scheduling are unchanged. Changing a generated Cloze note's Text also reconciles Cards with distinct positive indexes. Cards for indexes that remain keep their ID, scheduling, flag, and history; removed indexes lose their cards and new indexes receive safe AnkiScheduling.New state. Malformed or overflowing cloze indexes are rejected before either the field or cards are changed.

Exceptions

ArgumentNullException	value is null.
ArgumentException	name is not defined by NoteType.

Definition at line 142 of file AnkiNote.cs.

Property Documentation

Cards

IReadOnlyList<AnkiCard> AnkiIO.AnkiNote.Cards

get

Gets the study prompts currently generated for this note.

A live, non-castable read-only view in template or cloze-index order.

A detached note constructed directly starts empty. AnkiDeck.AddNote populates standard cards from templates or Cloze cards from markers. Modify scheduling/flags on the returned cards; do not try to add cards through this view.

Definition at line 128 of file AnkiNote.cs.

Fields

IReadOnlyDictionary<string, string> AnkiIO.AnkiNote.Fields

get

Gets this note's values keyed by the exact names in AnkiNoteType.Fields.

A live, non-castable read-only dictionary; use SetField to change a value safely.

Every defined field is present, including fields omitted at construction (stored as empty strings). Values may be HTML and may refer to registered media by filename. Enumeration follows note-type field order only where the chosen dictionary/runtime preserves insertion order; use AnkiNoteType.Fields when order is semantically required.

Definition at line 110 of file AnkiNote.cs.

Guid

string AnkiIO.AnkiNote.Guid

get

Gets Anki's stable text identity used to match the same note during import/update workflows.

The caller-supplied GUID, or a generated ten-character value for new content.

This is not necessarily a System.Guid value. Preserve a source GUID when you expect a later import to update rather than duplicate a note; generate a new one for a genuinely distinct note.

Definition at line 97 of file AnkiNote.cs.

Id

long AnkiIO.AnkiNote.Id

get

Gets the persisted numeric identity shared by every card generated from this note.

The caller-supplied ID, or a process-generated positive ID.

Preserve imported IDs for round trips; explicit IDs must be unique across the exported graph.

Definition at line 89 of file AnkiNote.cs.

NoteType

AnkiNoteType AnkiIO.AnkiNote.NoteType

get

Gets the shared model that defines field order, rendering templates, CSS, and card generation.

The same instance supplied to the constructor, frozen against structural changes when this note was created.

Definition at line 101 of file AnkiNote.cs.

Tags

IReadOnlyCollection<string> AnkiIO.AnkiNote.Tags

get

Gets note-level labels used for organization and search in Anki.

A newly allocated, case-sensitive, ordinal-sorted read-only snapshot.

Tags apply to the note and therefore to all sibling cards. Use AnkiCard.Flag for a single-card marker. AnkiIO rejects whitespace inside one tag because legacy Anki storage separates tags with spaces. Hierarchical tag text such as language::german is allowed.

Definition at line 119 of file AnkiNote.cs.

---

The documentation for this class was generated from the following file:

• src/AnkiIO/AnkiNote.cs