Defining and Implementing Win32/COM/WinRT types in Rust

[kennykerr]

Authoring support is part of the next major milestone - stay tuned!

[kennykerr]

Rust presents both unique challenges and unique opportunities when it comes to creating a language projection for the Windows Runtime. Defining and implementing COM and WinRT types in Rust highlights how this language’s rich metaprogramming facilities allow developers rather ingenious flexibility to hook compilation for both importing and exporting type information.

Today, Rust/WinRT lets you import WinRT types from metadata. The resulting imported types are projected as Rust types that are callable in an idiomatic way. This however only covers consumption of types. Now it's time to explore how Rust/WinRT is being extended to allow COM and WinRT types to be defined in Rust, for local consumption and optionally for export as well, and to allow Rust implementations of both imported or locally defined types.

The problem can be broken down as follows:

• Declare WinRT and COM types in Rust
• Implement WinRT and COM classes in Rust
• Export the metadata representation of those types as a winmd file

Today, a Rust project imports types using either the winrt::import or winrt::build macros. Either way, a set of winmd files are gathered and the aggregate of all types are available for import into the Rust type system. This acts as a sort of cache of metadata that is at the Rust project’s disposal. This is important because the import/build macros don’t know ahead of time what types might need to be implemented by the project. Breaking down the problem like this is useful because you can quickly see how the solution comes together. Locally declared WinRT and COM types are immediately exported to a winmd file that is then added to the metadata cache that is then available to any COM and WinRT implementations within the Rust project. The winmd file can then be shared with other projects as needed.

To complement the winrt import/build macros, Rust/WinRT adds the winrt::implements attribute macro to implement any previously declared COM or WinRT classes and interfaces. This macro draws information from the metadata cache to fill in the scaffolding and boilerplate code necessary to implement the desired types in Rust.

Here is an example of how the build macro might be used (and updated) to both import existing type information and declare new project-specific types.

winrt::build! {
    [import]
    windows::foundation::*
    windows::data::xml::dom::*
 
    [export]
    pub mod microsoft {
        pub mod windows {
            pub struct StructType { x: i32, y: i32 };
 
            pub interface IInterfaceType {
                fn method(&self) -> Result<StructType>;
            }
 
            pub class ClassType : IInterfaceType;
        }
    }
}

Then inside the project, any of the classes may be implemented using the winrt::implements macro:

#[winrt::implements(microsoft::windows::ClassType)]
pub struct ClassType {
    fields: u32
}

impl ClassType {
    pub method(&self) -> Result<StructType> {
        Ok(StructType{ x: 1, y: 2 })
    }
}

Because the type information is available to the implements macro, the developer doesn’t need to tell it which interfaces to implement or which methods to expect from the struct implementation. The implements macro also has enough information to build up the necessary vtable pointers and slots to support the COM object at run time.

The implements macro in its simplest form may be used simply to implement an existing WinRT class:

#[winrt::implements(windows::foundation::Uri)]
pub struct Uri { ... }

The implementation will automatically include the windows::foundation::Uri class’ required interfaces, including IUriRuntimeClass, IUriRuntimeClassWithAbsoluteCanonicalUri, and IStringable in this case. The Uri struct will be expected to provide implementations for the methods of all of these interfaces.

The implements macro may also be used to implement a loose set of interfaces:

#[winrt::implements(IFrameworkViewSource, IFrameworkView)]
pub struct App { ... }

In this case, the struct will implement the indicated interfaces and nothing more. This is useful for implementations that don’t necessarily correspond to a WinRT class. Generic and polymorphic implementations of IVector<T> and other collection interfaces may be implemented in this manner as well.

Finally, the implements macro may be used to implement a combination of classes and interfaces:

#[winrt::implements(windows::foundation::SomeClass, ISomethingWinRT, ISomethingCom)]
pub struct Uri { ... }

In this case, the struct will implement all of the interfaces required by SomeClass as well as the loose interfaces indicated by the attribute.

[robmikh]

I think this all sounds great! I have some questions, hopefully they aren't too in the weeds:

1. The whole exporting bit is very interesting. And I'm assuming that most people who want to export types/metadata will use that path. Do you see that part also handling exporting DllGetActivationFactory and the like? I'm mainly asking because I think versioning might still be easier by authoring an idl, but that's a much narrower scenario (in fact it might only matter to the system). It might be useful to "export" types from existing metadata.

2. In the last example, where you can implement a COM/non-WinRT interface, I'm guessing that includes arbitrary types that implement the ComInterface trait?

[kennykerr]

@robmikh

Yes, export implies both the production of the winmd file directly from the Rust build as well as the DllGetActivationFactory implementation that provides access to all of the public WinRT classes that the Rust project implements, allowing you to create a DLL. You can of course still use IDL and then simply import the resulting winmd file and implement some of the existing WinRT classes. Either way (whether the WinRT class is declared locally or imported) there needs to be a step that gathers up all of the public WinRT classes and exports them via DllGetActivationFactory.

I'd like to support the same kind of versioning support that IDL affords directly from Rust. While I think using IDL is fine, I don't want developers to resort to IDL merely because Rust lacks support for versioned interfaces (or anything else). We should be able to easily use attributes to declare interfaces as being required, static, and activatable interfaces of a given WinRT class just as you can in IDL today with all of the same attributes for versioning, noexcept, overloads, renames, properties, and so on.

The trouble with your second question is that a procedural macro like implements doesn't have access to the compilation unit as a whole that may declare other interfaces via something like a ComInterface trait. It only works as I've described above because the implements macro can look at the metadata that was previously collected and synthesized by the build macro. The assumption for COM interfaces is that they too will be imported or declared via the build macro.

[rylev]

I'm not sure that this can work since it would need to be guaranteed that the winrt::build! macro runs before all the winrt::implements macros which I don't think we can guarantee.

Where does the exported metadata end up? If I take a dependency on a project that exports certain types, how do I read the metadata from that dependency?

Other than that I like idea. Granted I don't think that this type of solution has too much precedent, but I think it largely avoids most of the bad practices you sometimes encounter in proc_macros (e.g., network access).

[kennykerr]

@rylev

The assumption is that the build macro runs in a sub crate, as is the norm anyway. That should ensure that it runs before hand. Here's an example.

Exporting metadata (and implementations) produces a WinRT component, not a Rust library crate. The resulting build artifacts would be distributed as a nuget package so that any language, not just Rust, can consume that WinRT component. Of course the implementing Rust crate can still be directly consumed by other Rust crates as a dependency and sidestep the WinRT indirection.