Skip to content

Commit 580be78

Browse files
sharwellsharwell
committed
Merge pull request #313 from sharwell/async-docs
Updated Asynchronous Services documentation
2 parents 657cdb8 + 26eb010 commit 580be78

1 file changed

Lines changed: 179 additions & 6 deletions

File tree

‎src/Documentation/Content/AsynchronousServices.aml‎

Lines changed: 179 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,187 @@
66

77
<introduction>
88
<para>
9-
The openstack.net SDK is migrating to an asynchronous service model for ongoing feature support.
9+
The openstack.net SDK is migrating to an asynchronous service model using the
10+
<externalLink>
11+
<linkText>Task-based Asynchronous Pattern (TAP)</linkText>
12+
<linkAlternateText>Task-based Asynchronous Pattern (TAP) (Microsoft Developer Network)</linkAlternateText>
13+
<linkUri>http://msdn.microsoft.com/en-us/library/hh873175.aspx</linkUri>
14+
</externalLink>
15+
for ongoing feature support.
1016
This page contains information about several aspects of the asynchronous interfaces which could
1117
result in some confusion during development. It also describes the inclusion of extension methods
1218
that allow new product features to be used in code that is not allowed to make asynchronous API
1319
calls.
1420
</para>
1521
</introduction>
1622

23+
<section address="LanguageSupport">
24+
<title>Language Support for Asynchronous Programming</title>
25+
<content>
26+
<para>
27+
Support for asynchronous interfaces in this library takes advantage of two recent advancements
28+
in asynchronous programming support in .NET. First, the <token>TaskParallelLibrary</token>
29+
added base library support for creating asynchronous tasks. Second, language improvements allow
30+
for these tasks to be naturally and efficiently used within code. Depending on the environment
31+
used by your project, you may need to take additional steps in order to use these features.
32+
</para>
33+
<para>
34+
The Task Parallel Library is used extensively by the implementation of this SDK. The library was
35+
originally added as part of .NET 4, users still working with .NET 3.5 make use of the
36+
<externalLink>
37+
<linkText>Task Parallel Library for .NET 3.5</linkText>
38+
<linkUri>http://www.nuget.org/packages/TaskParallelLibrary/</linkUri>
39+
</externalLink>
40+
package using NuGet. This package is automatically installed by NuGet when the SDK package is
41+
added to a project targeting .NET 3.5.
42+
</para>
43+
<para>
44+
Language support varies by language. The following table shows the language features available
45+
for several language, along with special considerations for use.
46+
</para>
47+
<table>
48+
<tableHeader>
49+
<row>
50+
<entry>
51+
<para>Language</para>
52+
</entry>
53+
<entry>
54+
<para>Keywords</para>
55+
</entry>
56+
<entry>
57+
<para>Visual Studio</para>
58+
</entry>
59+
<entry>
60+
<para>.NET Framework</para>
61+
</entry>
62+
</row>
63+
</tableHeader>
64+
<row>
65+
<entry>
66+
<para>C#</para>
67+
</entry>
68+
<entry>
69+
<para>
70+
<markup>
71+
<span class="input">async</span>/<span class="input">await</span>
72+
</markup>
73+
</para>
74+
</entry>
75+
<entry>
76+
<para>
77+
<externalLink>
78+
<linkText>Supported starting in Visual Studio 2012</linkText>
79+
<linkAlternateText>Asynchronous Programming with Async and Await (C# and Visual Basic) (Microsoft Developer Network)</linkAlternateText>
80+
<linkUri>http://msdn.microsoft.com/en-us/library/hh191443.aspx</linkUri>
81+
</externalLink>
82+
</para>
83+
<para>
84+
Can compile in Visual Studio 2010 if <codeInline>UseHostCompilerIfAvailable</codeInline> is
85+
set to <codeInline>false</codeInline> (see below)
86+
</para>
87+
</entry>
88+
<entry>
89+
<para>Supported in .NET 4.5+</para>
90+
<para>
91+
<externalLink>
92+
<linkText>Available via NuGet for .NET 4</linkText>
93+
<linkAlternateText>Microsoft Async (NuGet Gallery)</linkAlternateText>
94+
<linkUri>http://www.nuget.org/packages/Microsoft.Bcl.Async/</linkUri>
95+
</externalLink>
96+
</para>
97+
</entry>
98+
</row>
99+
<row>
100+
<entry>
101+
<para>Visual Basic</para>
102+
</entry>
103+
<entry>
104+
<para>
105+
<markup>
106+
<span class="input">Async</span>/<span class="input">Await</span>
107+
</markup>
108+
</para>
109+
</entry>
110+
<entry>
111+
<para>
112+
<externalLink>
113+
<linkText>Supported starting in Visual Studio 2012</linkText>
114+
<linkAlternateText>Asynchronous Programming with Async and Await (C# and Visual Basic) (Microsoft Developer Network)</linkAlternateText>
115+
<linkUri>http://msdn.microsoft.com/en-us/library/hh191443.aspx</linkUri>
116+
</externalLink>
117+
</para>
118+
<para>
119+
Can compile in Visual Studio 2010 if <codeInline>UseHostCompilerIfAvailable</codeInline> is
120+
set to <codeInline>false</codeInline> (see below)
121+
</para>
122+
</entry>
123+
<entry>
124+
<para>Supported in .NET 4.5+</para>
125+
<para>
126+
<externalLink>
127+
<linkText>Available via NuGet for .NET 4</linkText>
128+
<linkAlternateText>Microsoft Async (NuGet Gallery)</linkAlternateText>
129+
<linkUri>http://www.nuget.org/packages/Microsoft.Bcl.Async/</linkUri>
130+
</externalLink>
131+
</para>
132+
</entry>
133+
</row>
134+
<row>
135+
<entry>
136+
<para>Visual C++</para>
137+
</entry>
138+
<entry>
139+
<para>Not available</para>
140+
</entry>
141+
<entry>
142+
<para>Not available</para>
143+
</entry>
144+
<entry>
145+
<para>Not available</para>
146+
</entry>
147+
</row>
148+
<row>
149+
<entry>
150+
<para>F#</para>
151+
</entry>
152+
<entry>
153+
<para>
154+
<markup>
155+
<span class="input">async</span>/<span class="input">let!</span>
156+
</markup>
157+
</para>
158+
</entry>
159+
<entry>
160+
<para>Visual Studio 2010+</para>
161+
</entry>
162+
<entry>
163+
<para>Supported in .NET 4+</para>
164+
</entry>
165+
</row>
166+
</table>
167+
</content>
168+
<sections>
169+
<section>
170+
<title>Compiling projects with async/await in Visual Studio 2010</title>
171+
<content>
172+
<para>
173+
To compile C# or Visual Basic projects which use the newer language support for asynchronous
174+
programming in Visual Studio 2010, the
175+
<externalLink>
176+
<linkText>in-process compiler</linkText>
177+
<linkAlternateText>A Tale of Two Compilers (MSDN Blogs)</linkAlternateText>
178+
<linkUri>http://blogs.msdn.com/b/ed_maurer/archive/2008/06/11/a-tale-of-two-compilers.aspx</linkUri>
179+
</externalLink>
180+
must be disabled. This is performed by manually editing the project file to include the following
181+
as the last element of the first <codeInline>&lt;PropertyGroup&gt;</codeInline> section in the
182+
project file.
183+
</para>
184+
<code language="xml">&lt;UseHostCompilerIfAvailable&gt;false&lt;/UseHostCompilerIfAvailable&gt;</code>
185+
</content>
186+
</section>
187+
</sections>
188+
</section>
189+
17190
<section address="Exceptions">
18191
<title>Exceptions Thrown by Asynchronous Methods</title>
19192
<content>
@@ -30,9 +203,9 @@
30203
<codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference> object representing the
31204
asynchronous operation must be caught directly by the calling code. For example, if the code
32205
throws an <codeEntityReference>T:System.ArgumentNullException</codeEntityReference> in this
33-
manner, the calling code would need to contain a
34-
<codeInline>catch(ArgumentNullException)</codeInline> or
35-
<codeInline>catch(ArgumentException)</codeInline> handler to handle the exception.
206+
manner, the calling code would need to contain an exception handler for
207+
<codeEntityReference>T:System.ArgumentNullException</codeEntityReference> or
208+
<codeEntityReference>T:System.ArgumentException</codeEntityReference> to handle the exception.
36209
</para>
37210
</listItem>
38211
<listItem>
@@ -44,8 +217,8 @@
44217
<codeEntityReference>P:System.Threading.Tasks.Task.Exception</codeEntityReference> property, or
45218
by calling <codeEntityReference autoUpgrade="true">M:System.Threading.Tasks.Task.Wait</codeEntityReference>
46219
or checking the <codeEntityReference>P:System.Threading.Tasks.Task`1.Result</codeEntityReference>
47-
property within an exception handling block that includes a
48-
<codeInline>catch(AggregateException)</codeInline> handler.
220+
property within an exception handling block that includes a handler for
221+
<codeEntityReference>T:System.AggregateException</codeEntityReference>.
49222
</para>
50223
</listItem>
51224
</list>

0 commit comments

Comments
 (0)