forked from RallyTools/RallyRestToolkitFor.NET
-
Notifications
You must be signed in to change notification settings - Fork 0
/
DocumentationGeneration.shfbproj
308 lines (265 loc) · 16.1 KB
/
DocumentationGeneration.shfbproj
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
<PropertyGroup>
<!-- The configuration and platform will be used to determine which assemblies to include from solution and
project documentation sources -->
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>{95dfa21e-b8a8-46d3-be80-47a4f74d2168}</ProjectGuid>
<SHFBSchemaVersion>1.9.9.0</SHFBSchemaVersion>
<!-- AssemblyName, Name, and RootNamespace are not used by SHFB but Visual Studio adds them anyway -->
<AssemblyName>Documentation</AssemblyName>
<RootNamespace>Documentation</RootNamespace>
<Name>Documentation</Name>
<!-- SHFB properties -->
<FrameworkVersion>.NET Framework 4.0</FrameworkVersion>
<OutputPath>Documentation\</OutputPath>
<HtmlHelpName>RallyRestAPIForDotNetDocumentation</HtmlHelpName>
<Language>en-US</Language>
<BuildAssemblerVerbosity>OnlyWarningsAndErrors</BuildAssemblerVerbosity>
<HelpFileFormat>Website</HelpFileFormat>
<IndentHtml>True</IndentHtml>
<KeepLogFile>True</KeepLogFile>
<DisableCodeBlockComponent>False</DisableCodeBlockComponent>
<CppCommentsFixup>False</CppCommentsFixup>
<CleanIntermediates>True</CleanIntermediates>
<MaximumGroupParts>2</MaximumGroupParts>
<NamespaceGrouping>False</NamespaceGrouping>
<SyntaxFilters>Standard</SyntaxFilters>
<SdkLinkTarget>Blank</SdkLinkTarget>
<RootNamespaceContainer>False</RootNamespaceContainer>
<PresentationStyle>VS2013</PresentationStyle>
<Preliminary>False</Preliminary>
<NamingMethod>Guid</NamingMethod>
<HelpTitle>Rally Rest API for .Net</HelpTitle>
<FeedbackEMailAddress>support%40rallydev.com</FeedbackEMailAddress>
<ContentPlacement>AboveNamespaces</ContentPlacement>
<DocumentationSources>
<DocumentationSource sourceFile="Rally.RestApi\bin\Debug\Rally.RestApi.dll" />
<DocumentationSource sourceFile="Rally.RestApi.UiForWinforms\bin\Debug\Rally.RestApi.UiForWinforms.dll" />
<DocumentationSource sourceFile="Rally.RestApi.UiForWinforms\bin\Debug\Rally.RestApi.UiForWinforms.XML" />
<DocumentationSource sourceFile="Rally.RestApi.UiForWpf\bin\Debug\Rally.RestApi.UiForWpf.dll" />
<DocumentationSource sourceFile="Rally.RestApi.UiForWpf\bin\Debug\Rally.RestApi.UiForWpf.XML" />
<DocumentationSource sourceFile="Rally.RestApi\bin\Debug\Rally.RestApi.xml" />
</DocumentationSources>
<HtmlHelp1xCompilerPath>Documentation\</HtmlHelp1xCompilerPath>
<NamespaceSummaries>
<NamespaceSummaryItem name="Rally.RestApi.UiForWinforms" isDocumented="True"><p>This library provides a reusable UI for Winforms to provide common authentication.</p>
<p><i>NOTE: If you need IDP based SSO, you must use the UI for WPF instead as the IDP support was not implemented in the Winforms libraries.</i></p>
<p>This pseudo code example shows how to use the UI for Winforms. For a full working sample, please see the code in Test.Rally.RestApi.UiSample within the repository.</p>
<code language="C#">
public static RestApiAuthMgrWinforms winFormsAuthMgr { get; set; }
public static void PrimaryEntryMethod()
{
// HELP: Define your encryption items prior to instantiating authorization managers
// You must define your own private application token. This ensures that your login details are not overwritten by someone else.
string applicationToken = "RallyRestAPISample";
// You must set a user specific salt for encryption.
string encryptionKey = "UserSpecificSaltForEncryption";
// You must define your own encryption routines.
IEncryptionRoutines encryptionUtilities = new EncryptionUtilities();
// HELP: Instantiate authorization manager
winFormsAuthMgr = new RestApiAuthMgrWinforms(applicationToken, encryptionKey, encryptionUtilities);
// HELP: Configure labels for UI. These are global and used by the authentication manager to build their UI.
// If this is not called, the default labels will be used. In this sample we are changing a label and the default server URL.
ApiAuthManager.Configure(loginWindowServerLabelText: "My Updated Server Label", loginWindowDefaultServer: new Uri("http://onprem-url"));
// HELP: Set the logo that is shown in the login window
RestApiAuthMgrWinforms.SetLogo(ImageResources.RallyLogo40x40);
// Help: You can auto-authenticate if you want. We do not have it enabled for this application.
// winFormsAuthMgr.AutoAuthenticate(true);
}
// HELP: This method shows you how to open a login window.
private void openWinformsLogin_Click(object sender, RoutedEventArgs e)
{
// HELP: Delegates are provided so we can be notified that authentication or SSO authentication has completed.
winFormsAuthMgr.ShowUserLoginWindow(AuthenticationComplete, SsoAuthenticationComplete);
}
// HELP: This delegate notifies us that authentication has completed.
private void AuthenticationComplete(RallyRestApi.AuthenticationResult authenticationResult, RallyRestApi api)
{
UpdateAuthenticationResults(authenticationResult, api);
}
// HELP: This delegate notifies us that SSO authentication has completed.
private void SsoAuthenticationComplete(RallyRestApi.AuthenticationResult authenticationResult, RallyRestApi api)
{
UpdateAuthenticationResults(authenticationResult, api);
}
// HELP: This method handles the passthrough from the delegates.
// This is where you would need to update your application to show the logged in state.
private void UpdateAuthenticationResults(RallyRestApi.AuthenticationResult authenticationResult, RallyRestApi api)
{
// Change your applications behavoir based upon the new AuthenticationResult
}
</code></NamespaceSummaryItem>
<NamespaceSummaryItem name="Rally.RestApi.UiForWpf" isDocumented="True"><p>This library provides a reusable UI for WPF to provide common authentication.</p>
<p>This pseudo code example shows how to use the UI for WPF. For a full working sample, please see the code in Test.Rally.RestApi.UiSample within the repository.</p>
<code language="C#">
public static RestApiAuthMgrWpf wpfAuthMgr { get; set; }
public static void PrimaryEntryMethod()
{
// HELP: Define your encryption items prior to instantiating authorization managers
// You must define your own private application token. This ensures that your login details are not overwritten by someone else.
string applicationToken = "RallyRestAPISample";
// You must set a user specific salt for encryption.
string encryptionKey = "UserSpecificSaltForEncryption";
// You must define your own encryption routines.
IEncryptionRoutines encryptionUtilities = new EncryptionUtilities();
// HELP: Instantiate authorization manager
wpfAuthMgr = new RestApiAuthMgrWpf(applicationToken, encryptionKey, encryptionUtilities);
// HELP: Configure labels for UI. These are global and used by the authentication manager to build their UI.
// If this is not called, the default labels will be used. In this sample we are changing a label and the default server URL.
ApiAuthManager.Configure(loginWindowServerLabelText: "My Updated Server Label", loginWindowDefaultServer: new Uri("http://onprem-url"));
// HELP: Set the logo that is shown in the login window
RestApiAuthMgrWpf.SetLogo(ImageResources.RallyLogo40x40);
// Help: You can auto-authenticate if you want. We do not have it enabled for this application.
// wpfAuthMgr.AutoAuthenticate(true);
}
// HELP: This method shows you how to open a login window.
private void openWpfLogin_Click(object sender, RoutedEventArgs e)
{
// HELP: Delegates are provided so we can be notified that authentication or SSO authentication has completed.
wpfAuthMgr.ShowUserLoginWindow(AuthenticationComplete, SsoAuthenticationComplete);
}
// HELP: This delegate notifies us that authentication has completed.
private void AuthenticationComplete(RallyRestApi.AuthenticationResult authenticationResult, RallyRestApi api)
{
UpdateAuthenticationResults(authenticationResult, api);
}
// HELP: This delegate notifies us that SSO authentication has completed.
private void SsoAuthenticationComplete(RallyRestApi.AuthenticationResult authenticationResult, RallyRestApi api)
{
UpdateAuthenticationResults(authenticationResult, api);
}
// HELP: This method handles the passthrough from the delegates.
// This is where you would need to update your application to show the logged in state.
private void UpdateAuthenticationResults(RallyRestApi.AuthenticationResult authenticationResult, RallyRestApi api)
{
// Change your applications behavoir based upon the new AuthenticationResult
}
</code></NamespaceSummaryItem>
<NamespaceSummaryItem name="(global)" isDocumented="True" />
<NamespaceSummaryItem name="Rally.RestApi.Auth" isDocumented="True"><p>This namespace contains classes that control how the RestAPI toolkit authenticates with Rally.</p></NamespaceSummaryItem>
<NamespaceSummaryItem name="Rally.RestApi.Connection" isDocumented="True"><p>This namespace contains classes that control how the RestAPI toolkit connects and communicates with Rally.</p></NamespaceSummaryItem>
<NamespaceSummaryItem name="Rally.RestApi.Exceptions" isDocumented="True"><p>This namespace contains all of the specific exceptions that might be thrown by the RestAPI toolkit.</p></NamespaceSummaryItem>
<NamespaceSummaryItem name="Rally.RestApi.Json" isDocumented="True"><p>This namespace contains classes that control how the RestAPI toolkit works with JSON data received from Rally.</p></NamespaceSummaryItem>
<NamespaceSummaryItem name="Rally.RestApi.Response" isDocumented="True"><p>This namespace contains classes that define the responses the RestAPI toolkit will return after comunicating with Rally.</p></NamespaceSummaryItem>
<NamespaceSummaryItem name="Rally.RestApi" isDocumented="True"><p>This is the primary namespace for the Rally Rest API for DotNet.</p>
<h3>Introduction</h3>
The Rally REST API for .NET provides an intuitive interface to your Rally Data. It supports querying items in addition to individual item creates, reads, updates and deletes. It is compatible with any .NET 4.0 language (C#, VB.NET, F#, etc.)
<h3>Adding the API to your Solution</h3>
Add a reference to the Rally.RestApi.dll library or libraries from a new or existing project. Your project must have a Project Target Framework of .NET Framework 4 or higher.
<table width="550">
<tr>
<th>Library</th>
<th>Required</th>
<th>Used For</th>
</tr>
<tr>
<td>Rally.RestApi.dll</td>
<td>Yes</td>
<td>Communication with Rally</td>
</tr>
<tr>
<td>Rally.RestApi.UiForWinforms.dll</td>
<td>No</td>
<td>Provides a UI for Winforms applications</td>
</tr>
<tr>
<td>Rally.RestApi.UiForWpf.dll</td>
<td>No</td>
<td>Provides a UI for WPF applications<br/>
Can be used by Winforms applications that need IDP based SSO
</td>
</tr>
</table>
<h3>Sample Usage</h3>
<p>This sample code snippet shows how the Rally Rest API can be used by a console application:</p>
<code language="C#">string username = "paul@acme.com";
string password = "Just4Rally";
string serverUrl = "https://preview.rallydev.com";
// Initialize the REST API. You can specify a web service version if needed in the constructor.
RallyRestApi restApi = new RallyRestApi();
restApi.Authenticate(username, password, serverUrl, proxy: null, allowSSO: false);
//Create an item
DynamicJsonObject toCreate = new DynamicJsonObject();
toCreate["Name"] = "My Defect";
CreateResult createResult = restApi.Create("defect", toCreate);
//Update the item
DynamicJsonObject toUpdate = new DynamicJsonObject();
toUpdate["Description"] = "This is my defect.";
OperationResult updateResult = restApi.Update(createResult.Reference, toUpdate);
//Get the item
DynamicJsonObject item = restApi.GetByReference(createResult.Reference);
//Query for items
Request request = new Request("defect");
request.Fetch = new List&lt;string&gt;() { "Name", "Description", "FormattedID" };
request.Query = new Query("Name", Query.Operator.Equals, "My Defect");
QueryResult queryResult = restApi.Query(request);
foreach (var result in queryResult.Results)
{
//Process item as needed
}
//Delete the item
OperationResult deleteResult = restApi.Delete(createResult.Reference);
</code>
<h3>Logging</h3>
The Rally REST API for .NET provides the ability to log all requests and responses to aid in troubleshooting.
To enable this behavior simply configure one or more trace listeners at the Information level.
Below is an example App.config which will enable this:
<code language="xml" title="Example App.config">
&lt;?xml version="1.0" encoding="utf-8" ?&gt;
&lt;configuration&gt;
&lt;system.diagnostics&gt;
&lt;trace autoflush="true" indentsize="2"&gt;
&lt;listeners&gt;
&lt;add name="RallyRestApiUiSample" type="System.Diagnostics.TextWriterTraceListener
initializeData="RallyRestApiUiSample.log" /&gt;
&lt;remove name="Default" /&gt;
&lt;/listeners&gt;
&lt;/trace&gt;
&lt;/system.diagnostics&gt;
&lt;/configuration&gt;
</code>
<h3>Upgrading from Rally Rest API 2.x</h3>
<p>If you are upgrading from the 2.x series of the Rally Rest API for DotNet, the following major changes are known:</p>
<ul>
<li/>Reorganization of Namespaces - Moved many classes into sub-namespaces for better organization of code
<li/>Changes to Visibility - Many classes and methods had their visibility changed to make it easier to find the methods that a user should be calling, instead of internal helper functions.
<li/>Authenication sequence - Constructor no longer performs authentication
<li/>Reusable UI Layer - We added components for standardized login windows throughout all applications using the toolkit, including support for SSO
<li/>Exceptions - We added custom exceptions for Rally being unavailable (returning HTML error page), or JSON data being unable to be deserialized.
<li/>Code Comments - We greatly expanded on the code header comments that generate this help documentation.
</ul>
<p>This example shows the changes to authentication for a console application. For UI based applications, please see the documentation for the Rally.RestApi.UiForWpf Namespace for extended examples.</p>
<code language="C#">
// Old authentication in constructor
RallyRestApi restApi = new RallyRestApi("user@sandbox.com", "secret", "https://sandbox.rallydev.com", "v2.0");
// New authentication method
RallyRestApi restApi = new RallyRestApi(webServiceVersion: "v2.0");
restApi.Authenticate("user@sandbox.com", "secret", "https://sandbox.rallydev.com", allowSSO: false);
</code></NamespaceSummaryItem></NamespaceSummaries>
<ProjectSummary>
</ProjectSummary>
</PropertyGroup>
<!-- There are no properties for these groups. AnyCPU needs to appear in order for Visual Studio to perform
the build. The others are optional common platform types that may appear. -->
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' ">
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x64' ">
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x64' ">
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|Win32' ">
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|Win32' ">
</PropertyGroup>
<!-- Import the SHFB build targets -->
<Import Project="$(SHFBROOT)\SandcastleHelpFileBuilder.targets" />
</Project>