在哪里可以找到 Windows 运行时的概念文档? [英] Where do I find conceptual documentation for Windows Runtime?

问题描述

我正在尝试充分了解 Windows 运行时，以便就我的雇主将我们现有的应用程序移植到它所需要的内容提出建议.我找不到提供 API 工作原理技术概述的文档.

I'm trying to learn enough about Windows Runtime to make a recommendation about what it would entail for my employer to port our existing applications to it. I'm having trouble finding documentation that provides a technical overview of how the API works.

我所有的网络搜索似乎都让我MSDN 上的 API 参考，简洁到不可读.它记录了 API 类和方法的正式签名，但似乎假设读者已经知道如何组合在一起.每个方法的目的通常只是被描述为一个简短的句子片段，用空格而不是CamelCase来重述它的名字，并且除了类型声明中明显的之外，对限制、期望和不变量的进一步解释几乎是完全没有.(这与普通 Win32 API 参考文档中信息量相当大的备注"部分形成对比.

All my web searches seem to lead me to API reference on MSDN, which is terse to the point of unreadability. It documents the formal signatures of API classes and methods, but seems to assume that the reader already knows how things fit together. The purpose of each method is usually just described as a terse sentence fragment that restates its name with spaces instead of CamelCase, and further explanations about restrictions, expectations and invariants beyond what is evident in the type declarations are almost completely absent. (This contrasts with the fairly informative "Remarks" sections in the reference documentation of the ordinary Win32 API).

显然，我不应该使用此文档来初步了解 API 的工作原理.我应该使用什么?

Clearly, I'm not supposed to be using this documentation to develop an initial overview of how the API works. What am I supposed to be using?

在 MSDN 中移动 一级 有一个名为概念和架构的部分，还有一些听起来更有前景的编程概念和基础——但它们是什么实际上描述是对相当专业的主题的看似随机选择，当然不是我需要理解 API 参考的内容.

Moving one level up in MSDN there is a section with the promising name Concepts and architecture, and some even more promising-sounding Programming concepts and Fundamentals -- but what they actually describe is a seemingly random selection of fairly specialized topics, certainly not what I need to make sense of the API reference.

是否有我需要购买和阅读的书籍形式的官方文档?MSDN 之外的东西?我找不到的秘密 MSDN 链接?

Is there official documentation in book form that I need to buy and read? Something outside of MSDN? A secret MSDN link that I haven't been able to find?

我看过这个上一个问题 没有得到任何真正的答案，也许是因为它的措辞相当不透明，其中包含 5 美元的词，例如本体".为了更好地解释我正在寻找的内容，以下是一些问题示例，我希望我寻求的文档能够告诉我答案:

I've seen this previous question which didn't get any real answers, perhaps because the it was phrased rather opaquely with $5 words like "ontology". In an attempt to explain better what I'm looking for, here are some examples of questions I hope the documentation I seek would tell me the answers to:

(请注意，这些只是示例.我的主要目标是找到回答这些和类似问题的规范，而不是获得这些具体示例的答案.)

(Note that these are examples only. My primary goal is to find a specification that answers these and similar questions, rather than get answers to these specific examples.)

Windows.Networking.Sockets.StreamSocket 具有 Windows.Storage.Streams.IInputStream 类型的 InputStream 属性，我很清楚应该用来从套接字读取.但是IInputStream的唯一方法是ReadAsync，它读入IBuffer，而IBuffer是一个什么都不声明的接口但容量和大小属性.我如何获得正在读取的实际字节数?如果我自己实现了 IBuffer，系统将如何将它们交付给我?

Windows.Networking.Sockets.StreamSocket has an InputStream property of type Windows.Storage.Streams.IInputStream, which I'm clearly supposed to use to read from the socket. But the only method of IInputStream is ReadAsync which reads into an IBuffer, and IBuffer is an interface that declares nothing but capacity and size properties. How do I get at the actual bytes being read? If I implement IBuffer myself, how will the system deliver them to me?

经过数小时沮丧的点击和谷歌搜索，我初步断定接口是个谎言——IBuffer 不是任何人都可以实现的，但是 ReadAsync 特别想要一个 Windows.Storage.Streams.Buffer(没有 I)，不管它的类型声明是什么.然后看来我可以使用 DataReader 从 Buffer 读取实际字节.真的是这样吗?

After hours of frustrated clicking and googling, I have tentatively concluded that the interface is a lie -- IBuffer is not something anyone can implement, but ReadAsync wants specifically a Windows.Storage.Streams.Buffer (without the I), no matter what its type declaration says. Then it seems I can use DataReader to read the actual bytes from the Buffer. Is that really how it's supposed to go?

或

嗯，看起来 DataReader 有一个接受 IInputStream 的构造函数，所以也许我可以去掉 Buffer 中间人.然而，这似乎是错误的，因为 DataReader 的方法如 ReadBytes 是 同步 并且据说 WinRT 中的所有 I/O 都是异步的；IInputStream 的一个声明方法当然是.那么它是如何工作的?

Hmm, it looks like DataReader has a constructor that takes an IInputStream, so perhaps I can cut out the Buffer middleman after all. However, this seems to be wrong, because DataReader's methods such as ReadBytes are synchronous and supposedly all I/O in WinRT is asynchronous; certainly the one declared method of IInputStream is. So how does that work?

在更加沮丧的谷歌搜索和点击之后:哦，在 DataReader 中有一个 LoadAsync 方法可以做……一些事情.根据 MSDN，它从输入流加载数据"，但是使用它的约定是什么?我应该在构造 DataReader 后立即调用它一次，还是可以多次调用它以重复使用相同的 DataReader 进行下一次读取操作?DataReader 内部是否包含循环缓冲区?如果我尝试读取的字节数多于已经异步读取的字节数，会发生什么?ReadFoo 方法的超级简洁文档没有提到异常或错误条件；DataReader 或 IDataReader 的类文档也没有.

After more frustrated googling and clicking: Oh, there's a LoadAsync method in DataReader that does ... something. According to MSDN, it "loads data from the input stream", but what are the conventions for using it? Am I supposed to call it just once immediately after constructing the DataReader, or can I call it multiple times to reuse the same DataReader for the next read operation? Does DataReader contain a circular buffer internally? What happens if I try to read more bytes than have been read asynchronously already? The super-terse documentation of the ReadFoo methods mention no exceptions or error conditions; neither do the class documentation for DataReader or IDataReader.

或

显然应用程序可以是多线程的，因为 支持的 Win32 API 包括诸如 InterlockedCompareExchange、EnterCriticalSection 等.但是 CreateThread 和 RTL 的 _beginthreadex 似乎都不受支持，而且似乎没有任何 Java-ish Thread 类在任何地方WinRT 类层次结构.如何开始一个新线程?

Apparently apps can be multi-threaded, since the supported Win32 APIs include things like InterlockedCompareExchange, EnterCriticalSection and so forth. But neither CreateThread nor the RTL's _beginthreadex seem to be supported, and there doesn't appear to be any Java-ish Thread class anywhere in the WinRT class hierarchy. How does one start a new thread?

或

说到异步 I/O……我对异步 I/O 和完成延续的总体思路非常满意，但是 WinRT 中的确切规则是什么，例如，完成例程在哪个线程中被调用?如果它始终是我开始 I/O 操作的同一个线程(我希望如此！)，我是否需要确保它不时进入某种警报等待，以便系统有机会在那里调用我的代码?

Speaking about asynchronous I/O ... I'm quite comfortable with the general idea of asynchronous I/O and completion continuations, but what are the precise rules in WinRT for, say, which thread the completion routine is called in? If it's always the same thread I started the I/O operation from (which I hope!), do I need to make sure it enters some kind of alertable wait from time to time, so the system has a chance to call my code there?

或

维基百科声称​​WinRT 本质上是一个基于 COM 的 API，虽然依赖于增强的 COM." 这种增强"究竟是什么?如果我遵循 COM 规则和约定，我是否有被由于增强"而工作方式不同的东西所困扰的风险?或者，相反，由于增强功能，我可以做一些更容易的事情吗?

Wikipedia claims that "WinRT is essentially a COM-based API, although relying on an enhanced COM." What exactly is this "enhancement"? If I follow COM rules and conventions, do I risk being bitten by things that work differently due to "enhancements"? Or, conversely, is there things I can do easier because of the enhancement?

或

关于异步回调如何工作的唯一描述使它看起来非常特定于实现语言——它在 C#/CLR、JavaScript 和 C++/CX 之间看起来相当不同.这里的 COM/ABI 级别实际发生了什么?特别是，由于 API 文档似乎假定C++"表示C++/CX"，如果我改用 WRL，异步 I/O 将如何工作?或者只是await 和then 业务只是语言提供的糖，而真正的 ABI 总是在AsyncOperationWithProgressCompletedHandler 等，如 API 参考中所述?但这是一种委托类型；就 COM 而言，这甚至具有明确定义的含义吗?

The only description of how asynchronous callbacks work make it look like they are quite specific to the implementation language -- it looks fairly different between C#/CLR, JavaScript and C++/CX. What's actually happening at the COM/ABI level here? In particular, since the API documentation appears to assume that "C++" means "C++/CX", how does asynchronous I/O work if I use WRL instead? Or is it just the case that the await and then business is just language-provided sugar and the real ABI is always in terms of AsyncOperationWithProgressCompletedHandler and so forth, as described in the API reference? But that's a delegate type; does that even have a well-defined meaning in terms of COM?

推荐答案

我刚刚注意到 MSDN 上似乎有两个并行页面层次结构描述了 WinRT API:

I've just noticed that there seem to be two parallel page hierarchies on MSDN describing the WinRT API:

• Windows 应用商店应用开发 |API 参考 |Windows 应用商店应用的 Windows API 参考

这是我在问题中咆哮的几乎空洞的文档.但是，某些 API 元素也在

This is the almost vacuous documentation I rant about in the question. However, some of the API elements are also described in

• MSDN 库 |其他资源 |Windows 运行时 C++ 参考

稍微接近 COM 金属，偶尔包含有用的备注部分.例如，它的 IBuffer 页面显示IBuffer 的实现还必须实现 IBufferByteAccess 提供对实际字节的访问.

which is slightly closer to the COM metal, and occasionally contains useful Remarks sections. For example its page for IBuffer reveals that implementations of IBuffer must also implement IBufferByteAccess which provides access to the actual bytes.

这并不理想(而且似乎仍然隐含了很多信息)，但至少是一些东西.

It is not ideal (and still seems to leave a lot of information implicit), but it is at least something.

这篇关于在哪里可以找到 Windows 运行时的概念文档?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！