Skip to content

Commit 423bd2b

Browse files
sharwellsharwell
committed
Merge pull request #413 from sharwell/updated-docs
Updated docs
2 parents 3b73401 + b93457c commit 423bd2b

17 files changed

Lines changed: 651 additions & 85 deletions

‎src/Documentation/AdditionalReferenceDocumentation.shfbproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@
3131
<DocumentationSource sourceFile="..\packages\Newtonsoft.Json.5.0.8\lib\net40\Newtonsoft.Json.xml" />
3232
<DocumentationSource sourceFile="..\packages\SimpleRESTServices.1.3.0.1\lib\net40\SimpleRESTServices.dll" />
3333
<DocumentationSource sourceFile="..\packages\SimpleRESTServices.1.3.0.1\lib\net40\SimpleRESTServices.xml" />
34+
<DocumentationSource sourceFile="..\packages\Rackspace.Threading.1.1.0-beta001\lib\net40-client\Rackspace.Threading.dll" />
35+
<DocumentationSource sourceFile="..\packages\Rackspace.Threading.1.1.0-beta001\lib\net40-client\Rackspace.Threading.xml" />
3436
</DocumentationSources>
3537
</PropertyGroup>
3638
<!-- There are no properties for these groups. AnyCPU needs to appear in order for Visual Studio to perform

‎src/Documentation/Content/AsynchronousServices.aml‎

Lines changed: 76 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,9 @@
66

77
<introduction>
88
<para>
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.
16-
This page contains information about several aspects of the asynchronous interfaces which could
17-
result in some confusion during development. It also describes the inclusion of extension methods
9+
The openstack.net SDK is migrating to an asynchronous service model using the <token>TaskBasedAsync</token>
10+
for ongoing feature support. This page contains information about several aspects of the asynchronous interfaces
11+
which could result in some confusion during development. It also describes the inclusion of extension methods
1812
that allow new product features to be used in code that is not allowed to make asynchronous API
1913
calls.
2014
</para>
@@ -33,12 +27,8 @@
3327
<para>
3428
The Task Parallel Library is used extensively by the implementation of this SDK. The library was
3529
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.
30+
<token>TaskParallelLibrary35</token> package using NuGet. This package is automatically installed by NuGet
31+
when the SDK package is added to a project targeting .NET 3.5.
4232
</para>
4333
<para>
4434
Language support varies by language. The following table shows the language features available
@@ -182,6 +172,14 @@
182172
project file.
183173
</para>
184174
<code language="xml">&lt;UseHostCompilerIfAvailable&gt;false&lt;/UseHostCompilerIfAvailable&gt;</code>
175+
<alert class="important">
176+
<para>
177+
While the <codeInline>UseHostCompilerIfAvailable</codeInline> setting allows Visual Studio 2010 to
178+
compile C# and Visual Basic projects using <token>AsyncAwait</token>, the editor itself does not
179+
recognize these keywords. As a result, some functionality including but not limited to IntelliSense may
180+
not function if this option is used.
181+
</para>
182+
</alert>
185183
</content>
186184
</section>
187185
</sections>
@@ -193,11 +191,15 @@
193191
<para>
194192
Asynchronous methods are capable of throwing exceptions before creating a
195193
<codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference> or during the asynchronous
196-
execution of the task itself. The asynchronous service interfaces do not distinguish between these
194+
execution of the task itself. The documentation for asynchronous methods does not distinguish between these
197195
two cases, allowing for any of the specified exceptions to be thrown in either manner.
198196
</para>
199-
<list class="bullet">
200-
<listItem>
197+
</content>
198+
199+
<sections>
200+
<section>
201+
<title>Exceptions Prior to Task Creation</title>
202+
<content>
201203
<para>
202204
Exceptions thrown prior to the creation of the
203205
<codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference> object representing the
@@ -207,8 +209,14 @@
207209
<codeEntityReference>T:System.ArgumentNullException</codeEntityReference> or
208210
<codeEntityReference>T:System.ArgumentException</codeEntityReference> to handle the exception.
209211
</para>
210-
</listItem>
211-
<listItem>
212+
<code language="cs" region="ExceptionPriorToTaskCreation" source="..\Samples\CSharpCodeSamples\AsynchronousExceptionsExamples.cs"/>
213+
<code language="vb" region="ExceptionPriorToTaskCreation" source="..\Samples\VBCodeSamples\AsynchronousExceptionsExamples.vb"/>
214+
</content>
215+
</section>
216+
217+
<section>
218+
<title>Exceptions During Task Execution</title>
219+
<content>
212220
<para>
213221
Exceptions thrown during the asynchronous execution of the task are wrapped in an
214222
<codeEntityReference>T:System.AggregateException</codeEntityReference> object and returned by the
@@ -220,9 +228,54 @@
220228
property within an exception handling block that includes a handler for
221229
<codeEntityReference>T:System.AggregateException</codeEntityReference>.
222230
</para>
223-
</listItem>
224-
</list>
225-
</content>
231+
<para>
232+
This library additionally ensures that exceptions thrown by asynchronous operations are not wrapped in
233+
multiple layers of <codeEntityReference>T:System.AggregateException</codeEntityReference>. In other words,
234+
an <codeEntityReference>T:System.AggregateException</codeEntityReference> thrown during the asynchronous
235+
execution of a task will result in the
236+
<codeEntityReference>P:System.Threading.Tasks.Task.Exception</codeEntityReference> property returning an
237+
<codeEntityReference>T:System.AggregateException</codeEntityReference> with exactly one inner exception,
238+
which is the original <codeEntityReference>T:System.ArgumentException</codeEntityReference>. This
239+
guarantee simplifies the use of the API is languages that support <token>AsyncAwait</token>, since those
240+
operators automatically unwrap the first layer of
241+
<codeEntityReference>T:System.AggregateException</codeEntityReference>.
242+
</para>
243+
<code language="cs" region="ExceptionDuringTaskExecution" source="..\Samples\CSharpCodeSamples\AsynchronousExceptionsExamples.cs"/>
244+
<code language="vb" region="ExceptionDuringTaskExecution" source="..\Samples\VBCodeSamples\AsynchronousExceptionsExamples.vb"/>
245+
</content>
246+
</section>
247+
248+
<section>
249+
<title>Consistent Exception Handling</title>
250+
<content>
251+
<para>
252+
Applications implementing specialized handling for exception which occur during asynchronous calls have
253+
multiple options available for consistent handling. The simplest solution, when available, involves using
254+
<token>AsyncAwait</token>. These operators automatically unwrap the first exception instance in the
255+
<codeEntityReference>P:System.AggregateException.InnerExceptions</codeEntityReference> collection of an
256+
<codeEntityReference>T:System.AggregateException</codeEntityReference>, resulting in behavior that appears
257+
to calling code as though the exception was directly thrown by the invoked method. The second method
258+
involves treating the original call as a continuation of another task, ensuring that all exceptions are
259+
presented as an <codeEntityReference>T:System.AggregateException</codeEntityReference> to the exception
260+
handling code. The following code shows the application of this strategy to an existing asynchronous call.
261+
Note that the <codeEntityReference>T:Rackspace.Threading.CompletedTask</codeEntityReference> class and
262+
<codeEntityReference>Overload:Rackspace.Threading.CoreTaskExtensions.Then</codeEntityReference>
263+
extension method are part of the <token>RackspaceThreadingLibrary</token> separately from this SDK.
264+
</para>
265+
<code language="cs" region="AsynchronousMethodAsContinuation" source="..\Samples\CSharpCodeSamples\AsynchronousExceptionsExamples.cs"/>
266+
<code language="vb" region="AsynchronousMethodAsContinuation" source="..\Samples\VBCodeSamples\AsynchronousExceptionsExamples.vb"/>
267+
<para>
268+
Code using the continuation strategy for consistent error handling may benefit from the use of the
269+
<codeEntityReference>Overload:Rackspace.Threading.CoreTaskExtensions.Catch</codeEntityReference> methods,
270+
which are also part of the <token>RackspaceThreadingLibrary</token>. This extension method behaves in a
271+
manner similar to <token>Await</token>, automatically unwrapping the first exception instance in the
272+
<codeEntityReference>P:System.AggregateException.InnerExceptions</codeEntityReference> collection
273+
of an <codeEntityReference>T:System.AggregateException</codeEntityReference> before invoking the
274+
continuation function which handles the exception.
275+
</para>
276+
</content>
277+
</section>
278+
</sections>
226279
</section>
227280

228281
<section address="SynchronousExtensions">

‎src/Documentation/Content/Authentication/Authentication.aml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,7 @@
3030
<para>
3131
<codeEntityReference>T:net.openstack.Core.Providers.IIdentityProvider</codeEntityReference>:
3232
This interface is defines the basic methods for authenticating a client against a service.
33-
The interface follows an API similar to the <externalLink>
34-
<linkText>OpenStack Identity Service</linkText>
35-
<linkUri>http://docs.openstack.org/api/openstack-identity-service/2.0/content/</linkUri>
36-
</externalLink>.
33+
The interface follows an API similar to the <token>OpenStackIdentityService</token>.
3734
</para>
3835
</listItem>
3936
<listItem>

‎src/Documentation/Content/Authentication/HPAuthentication.aml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,7 @@
2828
and initialize its properties with the desired authentication credentials. The
2929
<codeEntityReference>T:net.openstack.Core.Domain.CloudIdentityWithProject</codeEntityReference>
3030
credentials class allows the <codeInline>tenantName</codeInline> and <codeInline>tenantId</codeInline>
31-
properties described in the HP documentation on <externalLink>
32-
<linkText>Scoped Tokens</linkText>
33-
<linkUri>http://docs.hpcloud.com/api/identity/#scoped-tokens</linkUri>
34-
</externalLink> to be defined.
31+
properties described in the HP documentation on <token>HpScopedTokens</token> to be defined.
3532
</para>
3633
<list class="bullet">
3734
<listItem>

0 commit comments

Comments
 (0)