Skip to content

Commit 4879b19

Browse files
Peter-SimpsonPeter-Simpson
committed
Update help content.
1 parent cd6da2f commit 4879b19

7 files changed

Lines changed: 224 additions & 41 deletions

‎Help/ASCOMLibrary.content‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,14 @@
22
<Topics>
33
<Topic id="3e0a4970-b422-4427-bb1e-789bb79e1b4f" visible="True" />
44
<Topic id="448ecc79-4087-401f-97ca-3e2af8022a62" visible="True" title="What is in each ASCOM Library package" />
5-
<Topic id="d0969e72-58ac-4f66-b725-8147769b8c5f" visible="True" isSelected="true" title="How to discover Alpaca devices (async methods)" />
5+
<Topic id="a99ce334-4008-4927-928e-833557065d59" visible="True" noFile="true" isExpanded="true" title="Asynchronous Library Methods (async await)">
6+
<Topic id="d0969e72-58ac-4f66-b725-8147769b8c5f" visible="True" title="How to discover Alpaca devices asynchronously" />
7+
<Topic id="d50074a5-fc2e-4a40-a4aa-dec52045953b" visible="True" isSelected="true" title="Introduction to asynchronous client extensions" />
8+
<Topic id="cc7f1bae-15ed-4d69-b238-5d857d570c88" visible="True" title="How to use the asynchronous Alpaca and COM client extensions" />
9+
</Topic>
610
<Topic id="822398fe-b7bc-4024-a1fd-f654bfe79771" visible="True" title="How to discover Alpaca devices (polling and events)" />
711
<Topic id="12148518-094b-48a0-a947-05b4d987c037" visible="True" />
8-
<Topic id="12358d8f-2ed9-4144-95a1-f23df8b29ab5" visible="True" title="How to let the user select an Alpaca device" />
912
<Topic id="1F10A6D1-2BD4-4570-8465-74FEC23F7AE2" visible="True" title="How to make Alpaca devices and COM drivers appear the same" />
10-
<Topic id="833dd117-2e34-412d-8d52-4f3fd2dee3b1" visible="True" title="The difference between Alpaca Devices and ASCOM Devices" />
13+
<Topic id="12358d8f-2ed9-4144-95a1-f23df8b29ab5" visible="True" title="How to let the user select an Alpaca device" />
14+
<Topic id="833dd117-2e34-412d-8d52-4f3fd2dee3b1" visible="True" title="The difference between Alpaca Devices and ASCOM Devices" tocTitle="Terminology: The difference between Alpaca Devices and ASCOM Devices" />
1115
</Topics>

‎Help/ASCOMLibraryHelp.shfbproj‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@
113113
<ItemGroup>
114114
<None Include="Async Methods.aml" />
115115
<None Include="AlpacaAndAscomDevices.aml" />
116+
<None Include="AsyncClientExtensions.aml" />
116117
<None Include="Introduction.aml" />
117118
<None Include="DeviceDriverPointers.aml" />
118119
<None Include="ApplicationDeveloperPointers.aml" />
@@ -121,6 +122,7 @@
121122
<None Include="How to select an Alpaca device.aml" />
122123
<None Include="SeamlessAlpacaAndCom.aml" />
123124
<None Include="PackageMapping.aml" />
125+
<None Include="UsingAsyncClientExtensions.aml" />
124126
</ItemGroup>
125127
<ItemGroup>
126128
<ContentLayout Include="ASCOMLibrary.content" />

‎Help/Async Methods.aml‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,49 +3,51 @@
33
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
44
<introduction>
55
<para>
6-
This topic describes the asynchronous methods that the library provides. Please see <link xlink:href="833dd117-2e34-412d-8d52-4f3fd2dee3b1">Alpaca devices and ASCOM devices</link> for information on the Alpaca device / ASCOM device terminology.
6+
This topic describes the asynchronous discovery methods that the library provides. Please see <link xlink:href="833dd117-2e34-412d-8d52-4f3fd2dee3b1">Alpaca devices and ASCOM devices</link>
7+
for information on the Alpaca device / ASCOM device terminology.
78
</para>
89
</introduction>
910

1011
<section address="TaskBasedMethods">
1112
<title>Task Based Asynchronous Methods</title>
1213
<content>
1314
<para>
14-
The purpose of discovery is to identify devices that can be controlled through the Alpaca protocol and the library provides this information as generic lists of <codeEntityReference linkText="AlpacaDevices">T:ASCOM.Alpaca.Discovery.AlpacaDevice</codeEntityReference>
15+
The purpose of discovery is to identify devices that can be controlled through the Alpaca protocol and the library provides this information as generic lists of
16+
<codeEntityReference linkText="AlpacaDevices">T:ASCOM.Alpaca.Discovery.AlpacaDevice</codeEntityReference>
1517
and <codeEntityReference linkText="AscomDevices">T:ASCOM.Alpaca.Discovery.AscomDevice</codeEntityReference>
1618
</para>
1719
<para>
1820
These two static async methods return .NET Tasks that can be awaited or manipulated with Task methods:
19-
<list class="bullet">
20-
<listItem>
21-
<legacyBold>Alpaca devices</legacyBold>: <codeEntityReference linkText="AlpacaDiscovery.GetAlpacaDevicesAsync()">M:ASCOM.Alpaca.Discovery.AlpacaDiscovery.GetAlpacaDevicesAsync(System.Int32,System.Int32,System.Int32,System.Double,System.Boolean,System.Boolean,System.Boolean,ASCOM.Common.Alpaca.ServiceType,ASCOM.Common.Interfaces.ILogger,System.Threading.CancellationToken)</codeEntityReference>
22-
</listItem>
23-
<listItem>
24-
<legacyBold>ASCOM devices</legacyBold>: <codeEntityReference linkText="AlpacaDiscovery.GetAscomDevicesAsync(DeviceTypes? deviceType)">M:ASCOM.Alpaca.Discovery.AlpacaDiscovery.GetAscomDevicesAsync(System.Nullable{ASCOM.Common.DeviceTypes},System.Int32,System.Int32,System.Int32,System.Double,System.Boolean,System.Boolean,System.Boolean,ASCOM.Common.Alpaca.ServiceType,ASCOM.Common.Interfaces.ILogger,System.Threading.CancellationToken)</codeEntityReference>
25-
</listItem>
26-
</list>
2721
</para>
22+
<list class="bullet">
23+
<listItem>
24+
<legacyBold>Alpaca devices</legacyBold>: <codeEntityReference linkText="AlpacaDiscovery.GetAlpacaDevicesAsync()">M:ASCOM.Alpaca.Discovery.AlpacaDiscovery.GetAlpacaDevicesAsync(System.Int32,System.Int32,System.Int32,System.Double,System.Boolean,System.Boolean,System.Boolean,ASCOM.Common.Alpaca.ServiceType,ASCOM.Common.Interfaces.ILogger,System.Threading.CancellationToken)</codeEntityReference>
25+
</listItem>
26+
<listItem>
27+
<legacyBold>ASCOM devices</legacyBold>: <codeEntityReference linkText="AlpacaDiscovery.GetAscomDevicesAsync(DeviceTypes? deviceType)">M:ASCOM.Alpaca.Discovery.AlpacaDiscovery.GetAscomDevicesAsync(System.Nullable{ASCOM.Common.DeviceTypes},System.Int32,System.Int32,System.Int32,System.Double,System.Boolean,System.Boolean,System.Boolean,ASCOM.Common.Alpaca.ServiceType,ASCOM.Common.Interfaces.ILogger,System.Threading.CancellationToken)</codeEntityReference>
28+
</listItem>
29+
</list>
2830
<para>
2931
Each method initiates a discovery when called and immediately returns an awaitable Task, enabling the calling method to continue processing while the discovery process runs. When discovery completes, the Task result is updated with a generic
3032
list of <codeEntityReference>T:ASCOM.Alpaca.Discovery.AlpacaDevice</codeEntityReference> or <codeEntityReference>T:ASCOM.Alpaca.Discovery.AscomDevice</codeEntityReference> as appropriate.
3133
</para>
3234
<para>
33-
Both asynchronous methods have parameters to customise discovery, however, all of these are optional and have default values, except for the <codeEntityReference>T:ASCOM.Common.DeviceTypes</codeEntityReference> parameter in the
35+
Both asynchronous methods have parameters to customise discovery, however, all of these are optional and have default values, except for the <codeEntityReference>T:ASCOM.Common.DeviceTypes</codeEntityReference> parameter in the
3436
<codeEntityReference linkText="AlpacaDiscovery.GetAscomDevicesAsync(DeviceTypes? deviceType)">M:ASCOM.Alpaca.Discovery.AlpacaDiscovery.GetAscomDevicesAsync(System.Nullable{ASCOM.Common.DeviceTypes},System.Int32,System.Int32,System.Int32,System.Double,System.Boolean,System.Boolean,System.Boolean,ASCOM.Common.Alpaca.ServiceType,ASCOM.Common.Interfaces.ILogger,System.Threading.CancellationToken)</codeEntityReference>
3537
method, which is a required parameter.
3638
</para>
3739
<para>
3840
These examples show how to use the static asynchronous methods:
39-
<code source="HelpExamples\AsyncMethodsAwait.cs" region="AsynchronousMethodsAwait1" language="csharp" title="Using the asynchronous methods" />
4041
</para>
42+
<code source="HelpExamples\AsyncMethodsAwait.cs" region="AsynchronousMethodsAwait1" language="csharp" title="Using the asynchronous methods" />
4143
<para>
4244
Named parameters are helpful when only a few parameters require non-default values:
43-
<code source="HelpExamples\AsyncMethodsAwait.cs" region="AsynchronousMethodsAwait2" language="csharp" title="Using named parameters" />
4445
</para>
46+
<code source="HelpExamples\AsyncMethodsAwait.cs" region="AsynchronousMethodsAwait2" language="csharp" title="Using named parameters" />
4547
<para>
4648
If required, you can also work directly with the tasks returned by these methods:
47-
<code source="HelpExamples\AsyncMethodsTask.cs" region="AsynchronousMethodsTask" language="csharp" title="Working with discovery tasks" />
4849
</para>
50+
<code source="HelpExamples\AsyncMethodsTask.cs" region="AsynchronousMethodsTask" language="csharp" title="Working with discovery tasks" />
4951
</content>
5052
</section>
5153
<bibliography></bibliography>

‎Help/AsyncClientExtensions.aml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<topic id="d50074a5-fc2e-4a40-a4aa-dec52045953b" revisionNumber="1">
3+
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
5+
<introduction>
6+
<para>
7+
The ASCOM interfaces support long running operations by means of an "Initiator / Completion variable" pattern in which a short running "initiator" method starts the operation and where a pollable "completion property"
8+
indicates when the operation has finished. Examples of this include:
9+
</para>
10+
<list class="bullet">
11+
<listItem>
12+
<para>
13+
Initiator: <legacyBold>ITelescope.SlewToCoordinatesAsync</legacyBold> - Completion Variable: <legacyBold>ITelescope.Slewing</legacyBold>
14+
</para>
15+
</listItem>
16+
<listItem>
17+
<para>
18+
Initiator: <legacyBold>ICamera.StartExposure</legacyBold> - Completion Variable: <legacyBold>ICamera.CameraState</legacyBold>
19+
</para>
20+
</listItem>
21+
<listItem>
22+
<para>
23+
Initiator: <legacyBold>IRotator.MoveAbsolute</legacyBold> - Completion Variable: <legacyBold>IRotator.IsMoving</legacyBold>
24+
</para>
25+
</listItem>
26+
</list>
27+
<para>
28+
The asynchronous extension methods, which work with both <legacyBold>Alpaca clients</legacyBold> and <legacyBold>COM clients</legacyBold>, encapsulate each long running process initiator / completion variable pair as a single Microsoft .NET
29+
<codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference>
30+
that can be awaited or assigned to a Task variable. This enables the client to wait for the process to complete asynchronously by using language features such as the await operator and Task.WhenAll(task1, task2).
31+
</para>
32+
<para>
33+
A list of extensions for all devices can be found here: <codeEntityReference linkText="List of Asynchronous Methods">T:ASCOM.Common.ClientExtensions</codeEntityReference>
34+
and each client's asynchronous methods are also listed in the "Extension Methods" section that follows the client's "Methods" section in the API documentation.
35+
</para>
36+
</introduction>
37+
38+
<section address="NamingVisibility">
39+
<title>Extension naming and visibility</title>
40+
<content>
41+
<para>
42+
In line with .NET naming conventions, the asynchronous extensions are named by taking their initiator method names and appending "Async". This works well in most cases apart from some ITelescope
43+
members whose names already end with Async. In these cases, to avoid names such as "SlewToTargetAsyncAsync", the text "Task" is inserted before the Async postfix. For example, the interface and
44+
extension methods for slewing a telescope to its target coordinates are:
45+
</para>
46+
<list class="bullet">
47+
<listItem>
48+
<para>
49+
ITelescope Interface: <legacyBold>ITelescope.SlewToTarget</legacyBold> - Synchronous method
50+
</para>
51+
</listItem>
52+
<listItem>
53+
<para>
54+
ITelescope Interface: <legacyBold>ITelescope.SlewToTargetAsync</legacyBold> - Asynchronous method with completion Variable ITelescope.Slewing
55+
</para>
56+
</listItem>
57+
<listItem>
58+
<para>
59+
ITelescope Extension: <legacyBold>ITelescope.SlewToTargetTaskAsync</legacyBold> - Returns an awaitable task that completes when the slew ends
60+
</para>
61+
</listItem>
62+
</list>
63+
<para>
64+
To use the client extensions add a using(C#) / Imports(VB.Net) statement referencing the ASCOM.Common namespace. The extension methods will then appear as additional methods of the Alpaca and COM clients.
65+
</para>
66+
</content>
67+
</section>
68+
69+
<section address="Exceptions">
70+
<title>Exceptions</title>
71+
<content>
72+
<para>
73+
When awaited, the extension methods will always return ASCOM exceptions. These can arrive immediately if thrown by the initiator or later if thrown by the completion variable.
74+
</para>
75+
<para>
76+
If the task returned by the extension method is assigned to a Task variable, behaviour is the same as when the task is awaited, except that all exceptions will be wrapped in
77+
<codeEntityReference>T:System.AggregateException</codeEntityReference>
78+
exceptions in line with normal behaviour of .NET Tasks. In these cases you will need to check the InnerExceptions property in order to find the actual ASCOM exception that was thrown.
79+
</para>
80+
</content>
81+
</section>
82+
83+
<bibliography>
84+
85+
</bibliography>
86+
87+
<relatedTopics>
88+
<link xlink:href="833dd117-2e34-412d-8d52-4f3fd2dee3b1"/>
89+
</relatedTopics>
90+
91+
</developerConceptualDocument>
92+
93+
</topic>

‎Help/Introduction.aml‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
This cross platform library targets .NET Standard 2.0 for broadest application across .NET frameworks and can be used in projects that target Linux, Raspberry Pi, MacOS and Windows.
88
</para>
99
<para>
10-
Please see <link xlink:href="833dd117-2e34-412d-8d52-4f3fd2dee3b1">Alpaca devices and ASCOM devices</link> for information on the Alpaca device / ASCOM device terminology.
10+
Please see <link xlink:href="833dd117-2e34-412d-8d52-4f3fd2dee3b1">Alpaca devices and ASCOM devices</link> for information on the Alpaca device / ASCOM device terminology used in the Library Help documentation.
1111
</para>
1212
<para>The library's capabilities, supported .NET frameworks and supported operating systems are described below.</para>
1313
</introduction>
@@ -26,13 +26,22 @@
2626
<listItem>
2727
<legacyBold>COM Client</legacyBold> - Toolkit that encapsulates a Windows COM device and presents it as a strongly typed class (conceptually similar to the Platform's DriverAccess component - Windows only)
2828
</listItem>
29+
<listItem>
30+
<legacyBold>Asynchronous Client Methods</legacyBold> - Extension methods for long running Alpaca and COM client operations that return awaitable
31+
<externalLink>
32+
<linkText>Microsoft Task asynchronous programming</linkText>
33+
<linkAlternateText>Go to Microsoft Task asynchronous programming on Microsoft .NET web site</linkAlternateText>
34+
<linkUri>https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/task-asynchronous-programming-model</linkUri>
35+
</externalLink>
36+
(TAP) Tasks. Each task encapsulates an operation that uses an "initiator / completion variable" combination (e.g. IFocuser.Move / IFocuser.IsMoving) and completes when the polled variable indicates that the operation has finished.
37+
</listItem>
2938
<listItem>
3039
<legacyBold>Cross Platform Utilities</legacyBold>
3140
<list class="bullet">
3241
<listItem>New ILogger logging framework including a built in console logger</listItem>
3342
<listItem>SOFA component, functionally equivalent to the Platform's SOFA component</listItem>
3443
<listItem>Transform component, functionally equivalent to the Platform's Transform component</listItem>
35-
<listItem>TraceLogger based on the Platform's TraceLogger component.</listItem>
44+
<listItem>TraceLogger similar to the Platform's TraceLogger component.</listItem>
3645
<listItem>ILogger console logger.</listItem>
3746
<listItem>Utilities - A range of utility functions that have no counterparts in .NET APIs.</listItem>
3847
</list>
@@ -75,10 +84,10 @@
7584
<legacyBold>ASCOM.Com.Components</legacyBold> - The COM client toolkit, Profile and Chooser components to support clients and drivers on Windows platforms.
7685
</listItem>
7786
<listItem>
78-
<legacyBold>ASCOM.Common.Components</legacyBold> - Common Interfaces, enums and other types shared by ASCOM Alpaca and COM projects.
87+
<legacyBold>ASCOM.Tools</legacyBold> - A set of support components to aid development of clients, drivers and Alpaca devices.
7988
</listItem>
8089
<listItem>
81-
<legacyBold>ASCOM.Tools</legacyBold> - A set of support components to aid development of clients, drivers and Alpaca devices.
90+
<legacyBold>ASCOM.Common.Components</legacyBold> - Common Interfaces, enums and other types shared by ASCOM Alpaca and COM projects.
8291
</listItem>
8392
</list>
8493
</content>
@@ -87,10 +96,10 @@
8796
<section address="PackageDependencies">
8897
<title>Package Dependencies</title>
8998
<content>
90-
<para>The Library only has dependencies on these packages:</para>
99+
<para>The Library has dependencies on these packages:</para>
91100
<list class="bullet">
92101
<listItem>
93-
<legacyBold>ASCOM.Exception.Library</legacyBold> - ASCOM Exception definitions that ensure inter-operation with Windows COM clients and drivers.
102+
<legacyBold>ASCOM.Exception.Library</legacyBold> - ASCOM Exception definitions that ensure inter-operation between Alpaca clients / devices and COM clients / drivers.
94103
</listItem>
95104
<listItem>
96105
<legacyBold>Microsoft supported .NET packages</legacyBold> - These provide C# Dynamic variable, Windows registry access and JSON serialisation / de-serialisation support.
@@ -120,7 +129,7 @@
120129
<listItem>MacOS - Apple Silicon</listItem>
121130
<listItem>Raspberry Pi - Arm32bit</listItem>
122131
<listItem>Raspberry Pi - Arm64bit</listItem>
123-
<listItem>Windows 7, 8, 10 and 11 - 32bit</listItem>
132+
<listItem>Windows 7, 8 and 10 - 32bit</listItem>
124133
<listItem>Windows 7, 8, 10 and 11 - 64bit</listItem>
125134
</list>
126135
</content>

0 commit comments

Comments
 (0)