winmd library

A Dart library for working with Windows Metadata (.winmd) files.

This library can be used to query Windows developer APIs, encompassing both unmanaged APIs like Win32 or COM, as well as modern APIs like Windows Runtime (WinRT) that include their own metadata.

The library consumes metadata in the ECMA-335 format, originally part of the Common Language Infrastructure (CLI) - a standardized interface offered by .NET libraries. Since its creation, Windows Metadata has served as a language-neutral specification of the Windows Runtime APIs. More recently, the same format has been utilized to provide machine-readable metadata for the traditional Win32 and COM APIs and Win32 APIs in the Windows Driver Kit (WDK) that have been available in Windows for many years.

While the ability to interpret this format from Dart is valuable for various reasons, the original motivation behind creating this package was to facilitate a Dart language projection of the Win32 API. Utilizing Windows Metadata allows the generation of a Win32 API projection programmatically, offering resilience against errors or changes over time.

Additionally, this library is utilized by the windows_* packages, which provide idiomatic Dart language projections of the Windows Runtime (WinRT) APIs.

Beyond these specific use cases, this package can be valuable for creating Windows utilities using Dart or Flutter.

To start using this library, obtaining a Scope is necessary. A Scope contains a named set of metadata. For most scenarios, you should retrieve a scope through one of the static methods of the MetadataStore class, which caches retrieved scopes.

To retrieve the latest Win32 metadata scope, you can use the following code:

final scope = await MetadataStore.loadWin32Metadata();

By default, the loadWin32Metadata method downloads the latest version of the NuGet package Microsoft.Windows.SDK.Win32Metadata and loads the metadata from it. If you prefer a different version, you can specify the version string as a parameter:

final scope =
  await MetadataStore.loadWin32Metadata(version: '52.0.65-preview');

To retrieve the latest WinRT metadata scope, you can use the following code:

final scope = await MetadataStore.loadWinRTMetadata();

Similar to the Win32 counterpart, the loadWinRTMetadata method downloads the latest version of the NuGet package Microsoft.Windows.SDK.Contracts and loads the metadata from it. If you prefer a different version, you can specify the version string as a parameter:

final scope =
  await MetadataStore.loadWinRTMetadata(version: '10.0.22621.755');

To retrieve the latest WDK metadata scope, you can use the following code:

// Win32 metadata also needs to be loaded to resolve references from WDK
// metadata
await MetadataStore.loadWin32Metadata();

final scope = await MetadataStore.loadWdkMetadata();

By default, the loadWdkMetadata method downloads the latest version of the NuGet package Microsoft.Windows.WDK.Win32Metadata and loads the metadata from it. If you prefer a different version, you can specify the version string as a parameter:

final scope =
  await MetadataStore.loadWdkMetadata(version: '0.9.9-experimental');

Note: If the metadata you want to load has already been downloaded and stored locally, loadWdkMetadata, loadWin32Metadata, or loadWinRTMetadata will load the metadata from the local storage instead of downloading it again.

You can get the list of downloaded NuGet packages as follows:

for (final package in LocalStorage.packages) {
  print(package);
}

Alternatively, a scope can be obtained directly from a Windows Metadata (.winmd) file, as follows:

final scope =
  MetadataStore.loadMetadataFromFile(File('path/to/file.winmd'));

From this point, the scope object can be interrogated for its children, particularly the collection of typeDef objects, which in turn contain Method, Field, Event, and Property members.

In general, the model presented by this package aligns with the APIs exposed by the IMetaDataImport2 COM interface exposed by rometadata.dll.

Classes

Architecture
The architectures supported by a specific Win32 method or struct.
ClassLayout
Layout information for the class referenced by a specified token.
CustomAttribute
A custom (named) attribute.
CustomAttributeParameter
A single parameter within a custom attribute.
Event
An event.
Field
A field.
FieldOffset
A tuple of a field and its byte offset within a parent struct.
GenericParam
A generic parameter.
GenericParamConstraint
A generic parameter constraint.
InterfaceImpl
Records the interfaces a type implements explicitly.
LocalStorage
A utility class for managing local storage of this package.
MdMerge
A utility class for merging WinRT metadata (.winmd) files using the mdmerge.exe executable.
MemberRef
A member reference.
MetadataStore
A class that manages the caching and retrieval of Windows Metadata (.winmd) files and provides methods to obtain metadata scopes for WDK, Win32, and WinRT.
Method
A method.
MethodImplementationFeatures
Contains values that describe method implementation features.
ModuleRef
A module reference.
NuGetPackage
Represents a NuGet package.
Parameter
A parameter or return type.
PEKind
A representation of the assembly file's portable executable format.
PinvokeMap
A P/Invoke method representation.
Property
A property object.
Scope
A metadata scope, which typically matches an on-disk file.
SpecialConstraints
Identifies special constraints on a generic parameter.
TokenObject
The base object for metadata objects.
TypeDef
Represents a TypeDef in the Windows Metadata file
TypeIdentifier
Represents a type, as for example used in a parameter.
TypeTuple
An intermediate representation of a segment of a signature.
UncompressedData
A utility class for uncompressing data from the metadata blob heap.

Enums

BaseType
Specifies a common language runtime Type, a type modifier, or information about a type in a metadata type signature.
BestFit
Convention for mapping Unicode characters in P/Invoke calls.
CallingConvention
Platform calling convention.
CodeType
Code type of contained code.
FieldAccess
Field accessibility information.
ImageType
The platform architecture targeted by an executable.
MemberAccess
Specifies member access.
MetadataType
Represents different types of metadata used by this package.
PreferredArchitecture
Indicates the preferred architecture for a requested typeDef.
StringFormat
Specifies how string types are interpreted.
StringMarshalConvention
Convention for marshalling P/Invoke function strings.
ThrowOnUnmappableChar
Convention for how the interop marshaler should respond to an unmappable character.
TokenType
The type of object represented by a given token.
TypeLayout
Specifies how fields are laid out in the type.
TypeVisibility
Specifies visibility of a type to other types.
Variance
Indicates the kind of variance for a delegate / interface generic parameter.
VtableLayout
Specifies virtual table layout.

Mixins

CustomAttributesMixin
Represents an object that has custom (named) attributes associated with it.
GenericParamsMixin
Represents an object that contains generic parameters.
SupportedArchitecturesMixin
Represents an object that may have an attribute for supported platform architectures.

Constants

stringBufferSize → const int
Size used for Win32 string allocations.

Properties

CLDB_E_INDEX_NOTFOUND int
COM error returned when a token cannot be found.
final
CLDB_E_RECORD_NOTFOUND int
COM error returned when a Find* method returns no results.
final

Exceptions / Errors

WinmdException
An exception generated by the winmd package.