Codierungskonventionen für Metadaten-API
In diesem Thema werden die von der Metadaten-API verwendeten Codierungskonventionen erläutert.
Behandeln von Zeichenfolgenparametern
Die Metadaten-API macht alle Zeichenfolgen im Unicode-Format verfügbar. (Tatsächlich haben Symbolnamen auf Datenträgern das Format UTF-8, dieses ist aber für Metadaten-API-Clients nicht sichtbar.) Jede zurückgegebene Zeichenfolge setzt sich aus drei Parametern zusammen (die tatsächlichen Parameternamen variieren):
[in] ULONG cchString – Die Größe des Puffers in Bytes, in dem die Zeichenfolge, einschließlich des abschließenden NULL-Zeichens, zurückgegeben werden soll.
[out] LPCWSTR wzString – Ein Zeiger auf den Puffer, in dem die Zeichenfolge zurückgegeben wird.
[out] ULONG *pchString – Ein Zeiger auf die Größe der zurückgegebenen Zeichenfolge (einschließlich des abschließenden NULL-Zeichens). Wenn die Größe des Puffers nicht zum Speichern der vollständigen Zeichenfolge ausreicht, wird die zurückgegebene Zeichenfolge verkürzt und ein Fehlerhinweis zurückgegeben. Der Client kann den Puffer dann neu reservieren und es, wenn erforderlich, noch einmal versuchen.
Symbolnamen
Die folgenden Konventionen gelten für Symbolnamen von Zeichenfolgenparametern:
Es wird angenommen, dass Zeichenfolgenparameter, die Symbolnamen sind, immer auf NULL enden und kein [in]-Längenparameter erforderlich ist. Eingebettete NULL-Zeichen werden nicht unterstützt.
Wenn eine [in]-Parameterzeichenfolge zu groß ist, um ohne Verkürzung beibehalten zu werden, wird ein Fehler zurückgegeben.
Benutzerzeichenfolgen
Die folgenden Konventionen gelten für vom Benutzer bereitgestellte Zeichenfolgenparameter:
Benutzerzeichenfolgen weisen möglicherweise eingebettete NULL-Zeichen auf und sollten kein abschließendes NULL-Zeichen haben.
Eine Länge muss im cchString-Parameter angegeben werden. Die Größe des Puffers muss der genauen Länge der Zeichenfolge entsprechen, die gespeichert wird.
Speichern von Standardwerten
Konstanten können in Metadaten als Standardwerte für Felder, Parameter und Eigenschaften gespeichert werden. Drei Parameter werden verwendet, um eine Konstante anzugeben (die tatsächlichen Parameternamen variieren):
[in] DWORD dwCPlusTypeFlag – Ein Wert der CorElementType-Enumeration, der den Typ des Standardwerts angibt.
[in] void const *pValue – Ein Zeiger auf den tatsächlichen Standardwert. Ein Zeiger auf das 4-Byte-DWORD, in dem 0x0000002A enthalten ist, speichert beispielsweise einen DWORD-Dezimalwert von 42 in den Metadaten. Der (in dwCPlusTypeFlag angegebene) Typ des Standardwerts kann nur eine primitive Zeichenfolge oder eine Zeichenfolge sein. Wenn dwCPlusTypeFlag ELEMENT_TYPE_CLASS ist, dann ist der Standardwert NULL.
[in] ULONG cchValue – Die Anzahl der Unicode-Zeichen in der Bytesequenz, auf die pValue zeigt. Dies ist nur erforderlich, wenn der in dwCPlusTypeFlag angegebene Typ ELEMENT_TYPE_STRING ist. In allen anderen Fällen wird die Länge vom Typ abgeleitet.
Standardwerte werden nicht automatisch in Initialisierungscode oder statisch initialisierte Datenbereiche eingefügt. Sie werden einfach in Metadaten aufgezeichnet.
Um anzugeben, dass Sie keinen Standardwert angeben möchten, legen Sie alle Bits von dwCPlusTypeFlag fest (d. h., Sie legen den Wert auf -1 fest).
NULL-Zeiger für Rückgabeparameter
Da Metadaten-APIs nur ein Minimum an Fehlerüberprüfungen durchführen, erwarten sie unter folgenden Bedingungen einen Nicht-NULL-Zeiger für Rückgabeparameter:
In Define-Methoden ist ein Nicht-NULL-Zeiger für das zurückgegebene Token erforderlich. Diese Methoden erstellen das Element, das Sie definieren möchten, und geben ein Token für das Element zurück. Wenn Sie das Token nicht benötigen, können Sie es verwerfen.
Find-Methoden geben immer das Token für das Element zurück, wenn es erfolgreich gefunden wurde.
In Get-Methoden können Sie NULL in Parametern übergeben, die Sie nicht zurückbenötigen.
In Set-Methoden gibt es im Allgemeinen keinen Rückgabewert. Sie übergeben das Token für das zu aktualisierende Element zusammen mit den zu aktualisierenden Werten. Diese Methoden führen dann die Aktualisierung durch.
Zu ignorierende Parameterwerte
Einige Methoden in der Metadaten-API ermöglichen Ihnen, die Eigenschaften eines bereits definierten Elements zu ändern. Im folgenden Beispiel werden mithilfe der IMetaDataEmit::SetFieldProps-Methode die Eigenschaften eines Felds geändert, die zuvor durch einen Aufruf von IMetaDataEmit::DefineField bereitgestellt wurden:
HRESULT SetFieldProps(mdFieldDef fd, DWORD dwFieldFlags,
DWORD dwDefType, void const *pValue, ULONG cchValue)
Möglicherweise möchten Sie in manchen Fällen dwFieldFlags ändern, aber nicht pValue (oder umgekehrt). In diesem Fall müssen Sie, auch wenn Sie den Wert nicht ändern möchten, einen Parameterwert übergeben, um einen Fehler zu vermeiden. Sie können jedoch einen bestimmten Wert übergeben, der angibt, dass das Argument ignoriert werden soll, wenn Sie den Wert nicht ändern möchten. Metadaten-APIs verwenden die folgenden Konventionen, um anzugeben, dass ein Methodenargument ignoriert werden soll:
Wenn der Parameter ein Zeigertyp ist, übergeben Sie einen NULL-Zeiger.
Wenn der Parameter ein Werttyp ist (in der Regel eine Bitmaske aus Flags), übergeben Sie einen Wert mit allen festgelegten Bits (-1).
Fehlerrückgaben
Fast alle Methoden in den Schnittstellen IMetaDataDispenserEx, IMetaDataEmit und IMetaDataImport geben einen HRESULT-Wert zurück, um ihre Ergebnisse anzugeben. Wenn der Vorgang erfolgreich war, lautet der Wert S_OK. Wenn der Aufruf nicht erfolgreich war, wird ein anderer Wert zurückgegeben, der die Ursache für das Fehlschlagen des Vorgangs beschreibt.
Für alle Metadaten-APIs gilt das folgende allgemeine Muster: Wenn der Aufrufer einen Zeichenfolgenpuffer bereitstellt, der zu klein ist und das Ergebnis nicht komplett aufnehmen kann, kopieren die APIs so viele Zeichen wie möglich. Sie geben jedoch den HRESULT-Wert CLDB_S_TRUNCATION anstelle von S_OK zurück.
Aufrufer der IMetadata-Schnittstellen sind Compiler oder Tools. Es ist wichtig, dass diese Aufrufer immer den Rückgabestatus für jeden Aufruf überprüfen, um Fehler zu ermitteln. In diesen Fällen weisen Fehlerbedingungen auf ein Problem beim direkten Aufrufer (z. B. einem Compiler) und nicht beim Endbenutzer (z. B. einem Anwendungsprogramm) hin.
Speicherverwaltung
Nach allgemeinem COM-Standard gibt der Aufrufer den Arbeitsspeicher frei, den der Aufgerufene belegt. Die Metadaten-Methoden arbeiten jedoch anders.
Viele Metadaten-Methoden geben [out]-Zeiger auf Arbeitsspeicherblöcke zurück. Dieser Arbeitsspeicher ist Teil des Metadatenheaps des Moduls und im Besitz der Common Language Runtime (CLR). Daher erhalten Sie einen direkten Zeiger in den arbeitsspeicherinternen Metadatenspeicher der CLR, und die Anwendung muss den Arbeitsspeicher nicht freigeben.
Generikaunterstützung
In .NET Framework, Version 2.0, wurden die Metadaten-APIs deutlich erweitert, um Generika zu unterstützen (manchmal auch als "parametrische Polymorphie" bezeichnet). Generika ähneln in gewisser Weise C++-Vorlagen. Ein Beispiel für die Definition einer generischen Klasse in C# sieht folgendermaßen aus:
public class Dictionary<Key, Val> { . . . }
In diesem Fall wird die Dictionary-Klasse mit zwei generischen Parametern mit den Namen Key und Val parametrisiert. Beim Instanziieren der Klasse wählt der Benutzer die Typen für die generischen Parameter aus, wie im folgenden Beispiel:
Dictionary<string, int> NameToPhone = new Dictionary<string, int>();
Dictionary<int, string> PhoneToName = new Dictionary<int, string>();