.NET Framework Support for Windows Store Apps and Windows Runtime

The Windows 8 and the .NET Framework 4.5 documentation sets are separate. If you press F1 to display Help on a type or member, reference documentation from the appropriate set is displayed. However, if you browse through the Windows Runtime reference you might encounter examples that seem puzzling:

• Topics such as the IIterable interface don't have declaration syntax for Visual Basic or C#. Instead, a note appears above the syntax section (in this case, ".NET: This interface appears as System.Collections.Generic.IEnumerable<T>"). This is because the .NET Framework and the Windows Runtime provide similar functionality with different interfaces. In addition, there are behavioral differences: IIterable has a First method instead of a GetEnumerator method to return the enumerator. Instead of forcing you to learn a different way of performing a common task, the .NET Framework supports the Windows Runtime by making your managed code appear to use the type you're familiar with. You won't see the IIterable interface in the IDE, and therefore the only way you'll encounter it in the Windows Runtime reference documentation is by browsing through that documentation directly.

• The SyndicationFeed constructor documentation illustrates a closely related issue: Its parameter types appear to be different for different languages. For C# and Visual Basic, the parameter types are String and Uri. Again, this is because the .NET Framework has its own String and Uri types, and for such commonly used types it doesn't make sense to force .NET Framework users to learn a different way of doing things. In the IDE, the .NET Framework hides the corresponding Windows Runtime types.

• In a few cases, such as the Windows.UI.Xaml.GridLength structure, the .NET Framework provides a type with the same name but more functionality. For example, a set of constructor and property topics are associated with GridLength, but they have syntax blocks only for Visual Basic and C# because the members are available only in managed code. In the Windows Runtime, structures have only fields. The Windows Runtime structure requires a helper class, Windows.UI.Xaml.GridLengthHelper, to provide equivalent functionality. You won't see that helper class in the IDE when you're writing managed code.

• In the IDE, Windows Runtime types appear to derive from Object. They appear to have members inherited from Object, such as Object.ToString. These members operate as they would if the types actually inherited from Object, and Windows Runtime types can be cast to Object. This functionality is part of the support that the .NET Framework provides for the Windows Runtime. However, if you view the types in the Windows Runtime reference documentation, no such members appear. The documentation for these apparent inherited members is provided by the Object reference documentation.

In more advanced programming scenarios, such as using a Windows Runtime component written in C# to provide the application logic for a Windows Store app built for Windows using JavaScript, such differences are apparent in the IDE as well as in the documentation. When your component returns an IDictionary<int, string> to JavaScript, and you look at it in the JavaScript debugger, you'll see the methods of IMap<int, string> because JavaScript uses the Windows Runtime type. Some commonly used collection types that appear differently in the two languages are shown in the following table:

In the Windows Runtime, IMap<K, V> and IMapView<K, V> are iterated using IKeyValuePair. When you pass them to managed code, they appear as IDictionary<TKey, TValue> and IReadOnlyDictionary<TKey, TValue>, so naturally you use System.Collections.Generic.KeyValuePair<TKey, TValue> to enumerate them.

The way interfaces appear in managed code affects the way types that implement these interfaces appear. For example, the PropertySet class implements IMap<K, V>, which appears in managed code as IDictionary<TKey, TValue>. PropertySet appears as if it implemented IDictionary<TKey, TValue> instead of IMap<K, V>, so in managed code it appears to have an Add method, which behaves like the Add method on .NET Framework dictionaries. It doesn't appear to have an Insert method.

For more information about using the .NET Framework to create a Windows Runtime component, and a walkthrough that shows how to use such a component with JavaScript, see Creating Windows Runtime Components in C# and Visual Basic in the Windows Dev Center.

To enable the natural use of the Windows Runtime in managed code, .NET Framework primitive types appear instead of Windows Runtime primitive types in your code. In the .NET Framework, primitive types like the Int32 structure have many useful properties and methods, such as the Int32.TryParse method. By contrast, primitive types and structures in the Windows Runtime have only fields. When you use primitives in managed code, they appear to be .NET Framework types, and you can use the properties and methods of the .NET Framework types as you normally would. The following list provides a summary:

• For the Windows Runtime primitives Int32, Int64, Single, Double, Boolean, String (an immutable collection of Unicode characters), Enum, UInt32, UInt64, and Guid, use the type of the same name in the System namespace.

• For UInt8, use System.Byte.

• For Char16, use System.Char.

• For the IInspectable interface, use System.Object.

• For HRESULT, use a structure with one System.Int32 member.

As with interface types, the only time you might see evidence of this representation is when your .NET Framework project is a Windows Runtime component that is used by a Windows Store app built using JavaScript.

Other basic, commonly used Windows Runtime types that appear in managed code as their .NET Framework equivalents include the Windows.Foundation.DateTime structure, which appears in managed code as the DateTimeOffset structure, and the Windows.Foundation.TimeSpan structure, which appears as the TimeSpan structure.

In a few cases, the fact that .NET Framework types appear in your code instead of Windows Runtime types requires action on your part. For example, the Windows.Foundation.Uri class appears as Uri in .NET Framework code. Uri allows a relative URI, but Windows.Foundation.Uri requires an absolute URI. Therefore, when you pass a URI to a Windows Runtime method, you must ensure that it's absolute. (See Passing a URI to the Windows Runtime.)

When you develop a Windows Store app for Windows using JavaScript, you might find that some parts of the application logic perform better in managed code, or are easier to develop. JavaScript can't use .NET Framework class libraries directly, but you can make the class library a .WinMD file. In this scenario, the Windows Runtime component is an integral part of the app, so it doesn't make sense to provide version attributes.

You can package a set of related UI controls in a reusable Windows Runtime component. The component can be marketed on its own or used as an element in the apps you create. In this scenario, it makes sense to use the Windows Runtime VersionAttribute attribute to improve compatibility.

You can package managed code from your existing desktop apps as a standalone Windows Runtime component. This enables you to use the component in Windows Store apps built using C++ or JavaScript, as well as in Windows Store apps built using C# or Visual Basic. Versioning is an option if there are multiple reuse scenarios for the code.