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 themdmerge.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
Typedefs
-
HCORENUM
= Pointer<
NativeType> - mdAssembly = mdToken
- mdAssemblyRef = mdToken
- mdCustomAttribute = mdToken
- mdEvent = mdToken
- mdExportedType = mdToken
- mdFieldDef = mdToken
- mdFile = mdToken
- mdGenericParam = mdToken
- mdGenericParamConstraint = mdToken
- mdInterfaceImpl = mdToken
- mdManifestResource = mdToken
- mdMemberRef = mdToken
- mdMethodDef = mdToken
- mdMethodSpec = mdToken
- mdModule = mdToken
- mdModuleRef = mdToken
- mdParamDef = mdToken
- mdPermission = mdToken
- mdProperty = mdToken
- mdSignature = mdToken
- mdString = mdToken
- mdToken = Uint32
- mdTypeDef = mdToken
- mdTypeRef = mdToken
- mdTypeSpec = mdToken
-
MDUTF8CSTR
= Pointer<
Uint8> -
PCCOR_SIGNATURE
= Pointer<
Uint8> -
PCOR_SIGNATURE
= Pointer<
Uint8> -
UVCP_CONSTANT
= Pointer<
Uint8>
Exceptions / Errors
- WinmdException
-
An exception generated by the
winmd
package.