{"id":111725,"date":"2025-10-24T07:00:00","date_gmt":"2025-10-24T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=111725"},"modified":"2025-10-24T08:53:38","modified_gmt":"2025-10-24T15:53:38","slug":"20251024-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20251024-00\/?p=111725","title":{"rendered":"The early history of the Windows Runtime PropertyValue and why there is a PropertyType.Inspectable that is never used"},"content":{"rendered":"

Some time ago, I mentioned that the Property\u00adValue.Create\u00adInspectable<\/code> method doesn’t create a Property\u00adValue<\/code><\/a> but instead just returns its parameter unchanged. I concluded with the remark, “Property\u00adValue.Create\u00adInspectable<\/code> even exist? I’m not sure. Perhaps it was added for completeness.”<\/p>\n

Since that article was written, I did some archaeology, and I think I found the answer.<\/p>\n

Originally, the Property\u00adValue<\/code> did wrap inspectables, which is the Windows Runtime name for what most languages call an “object”. The idea was that the Property\u00adSet<\/code> would be an IMap<String, Property\u00adValue><\/code>, meaning that it was an associative array mapping strings to Property\u00adValue<\/code> objects. These Property\u00adValue<\/code> objects could hold value types like integers, or they could hold reference types in the form of an IInspectable<\/code>, or they could hold arrays of value or reference types, or they could hold nothing at all (“empty”).<\/p>\n

In that original design, the Property\u00adValue.Create\u00adInspectable<\/code> method did return a Property\u00adValue<\/code> whose Type<\/code> was Property\u00adType.Inspectable<\/code>. Similarly, the Property\u00adValue.Create\u00adEmpty<\/code> method returned a Property\u00adValue<\/code> whose Type<\/code> was Property\u00adType.Empty<\/code>.<\/p>\n\n\n\n\n\n\n\n
Value<\/th>\nPropertyType
\npv.Type<\/tt><\/th>\n		Creation<\/th>\nRetrieval<\/th>\n<\/tr>\n
Nothing<\/td>\nEmpty<\/tt><\/td>\nCreateEmpty()<\/tt><\/td>\nN\/A<\/td>\n<\/tr>\n
Scalar type (e.g. Int32<\/tt>)<\/td>\nInt32<\/tt><\/td>\nCreateInt32(v)<\/tt><\/td>\npv.GetInt32()<\/tt><\/td>\n<\/tr>\n
Reference type<\/td>\nInspectable<\/tt><\/td>\nCreateInspectable(v)<\/tt><\/td>\npv.GetInspectable()<\/tt><\/td>\n<\/tr>\n
Array type (e.g. Int32[]<\/tt>)<\/td>\nInt32Array<\/tt><\/td>\nCreateInt32Array(v)<\/tt><\/td>\npv.GetInt32Array()<\/tt><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

You had to wrap inspectables and empties because the Property\u00adSet<\/code> was a mapping from strings to Property\u00adValue<\/code>. Everything had to be expressed as a Property\u00adValue<\/code>.\u00b9 The Property\u00adValue<\/code> was the fundamental variant type of the Windows Runtime.<\/p>\n

At some point, the team decided to change the design and let Property\u00adSet<\/code> to be a mapping from string to inspectable (object). If the associated value is an object, then you get the corresponding object. If the associated value is empty, then you get null. And if the associated value is a value type, then the value type is wrapped inside a Property\u00adValue<\/code>, and the Property\u00adValue<\/code> wrapper acts as the object.<\/p>\n

I don’t know why the team changed their mind, but I suspect one of the points in favor of the new design is that the new design matches how most languages already work: C#, JavaScript, Python, Ruby, Scheme, Java, Objective-C all follow the principle that any type can be expressed as an object. (The act of converting value types to objects is known as “boxing”.)<\/p>\n

In other words, the design change promoted IInspectable<\/code> to be the fundamental variant type, and the Property\u00adValue<\/code> was demoted to being the fundamental boxed type.<\/p>\n

A very large change was made to the Windows code base to update the design and to update all the code that had been using the old design. To make the conversion easier, the general shape of the new design matched the old design where it made sense. And this meant that Property\u00adValue.Create\u00adInspectable<\/code> and Property\u00adValue.Create\u00adEmpty<\/code> still existed as functions, but they didn’t do anything interesting. They remained for backward compatibility. Also remaining for backward compatibility are the enumeration values Empty<\/code> and Inspectable<\/code>. They remain defined, but nobody uses them.<\/p>\n

That takes us to what we have today:<\/p>\n\n\n\n\n\n\n\n
Value<\/th>\nPropertyType
\npv.Type<\/tt><\/th>\n		Creation<\/th>\nRetrieval<\/th>\n<\/tr>\n
Nothing<\/td>\nN\/A<\/td>\nnull<\/tt><\/td>\nnull<\/tt><\/td>\n<\/tr>\n
Scalar type (e.g. Int32<\/tt>)<\/td>\nInt32<\/tt><\/td>\nCreateInt32(v)<\/tt><\/td>\npv.GetInt32()<\/tt><\/td>\n<\/tr>\n
Reference type<\/td>\nN\/A<\/td>\nv<\/tt><\/td>\npv<\/tt><\/td>\n<\/tr>\n
Array type (e.g. Int32[]<\/tt>)<\/td>\nInt32Array<\/tt><\/td>\nCreateInt32Array(v)<\/tt><\/td>\npv.GetInt32Array()<\/tt><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

For backward compatibility, Create\u00adEmpty<\/tt> returns null<\/code> and Create\u00adInspectable<\/tt> returns its (non-null) parameter unchanged.<\/p>\n

In addition to aligning closer to a large number of popular languages, the new design simplifies the code required to store and retrieve a possibly-null reference in a Property\u00adSet<\/code>.<\/p>\n

\/\/ C#\r\n\r\n\/\/ Old design: CreateInspectable requires a non-null reference\r\nps.Insert(\"key\", v == null ? PropertyValue.CreateEmpty() : PropertyValue.CreateInspectable(v));\r\n\r\npv = ps.Lookup(\"key\");\r\nif (pv.Type == PropertyValue.Empty) {\r\n    v = null;\r\n} else {\r\n    v = pv.GetInspectable();\r\n}\r\n\r\n\/\/ New design: If it's null, then store null\r\nps.Insert(\"key\", v);\r\n\r\nv = ps.Lookup(\"key\");\r\n<\/pre>\n
If you want a function that returns the Property\u00adType<\/code> for an arbitrary inspectable, you can do this:<\/p>\n
\/\/ C#\r\nPropertyType WhatIsThisThing(object thing)\r\n{\r\n    if (thing is IPropertyValue pv) {\r\n        return pv.Type;\r\n    } else if (thing is null) {\r\n        return PropertyType.Empty;\r\n    } else {\r\n        return PropertyType.Inspectable;\r\n    }\r\n}\r\n\r\n\/\/ C# 9.0\r\nPropertyType WhatIsThisThing(object thing)\r\n{\r\n    return thing switch {\r\n        null => PropertyType.Empty,\r\n        IPropertyValue pv => pv.Type,\r\n        _ => PropertyType.Inspectable,\r\n    };\r\n}\r\n\r\n\/\/ C++\/WinRT\r\nPropertyType WhatIsThisThing(IInspectable const& thing)\r\n{\r\n    if (thing == nullptr) {\r\n        return PropertyType::Empty;\r\n    } else if (auto pv = thing.try_as<IPropertyValue>()) {\r\n        return pv.Type();\r\n    } else {\r\n        return PropertyType::Inspectable;\r\n    }\r\n}\r\n<\/pre>\n
\u00b9 Since Property\u00adValue<\/code> is a reference type, they could have decided to use a null pointer to represent the empty state. I assume they explicitly wrapped the empty state for uniformity, rather than forcing people to check for null before querying the Type<\/code>. Compare the JsonValue<\/code> which has an explicit object for representing the JSON null<\/code> rather than using a null pointer.<\/p>\n","protected":false},"excerpt":{"rendered":"
It used to be there because PropertyValue started out as the fundamental variant type before shifting focus to being the fundamental boxed type.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25,2],"class_list":["post-111725","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code","tag-history"],"acf":[],"blog_post_summary":"
It used to be there because PropertyValue started out as the fundamental variant type before shifting focus to being the fundamental boxed type.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/111725","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=111725"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/111725\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=111725"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=111725"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=111725"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}