Merge pull request #257 from watson-developer-cloud/rc-2.4.2

.NET SDK 2.4.2

Author: mediumTaj

CHANGELOG.md

@@ -1,102 +1 @@
-Change Log
-==========
-## Version 2.4.1
-_2018-06-20_
-* Regenerated SDK based on the latest API definition.
-* Added IAM authentication support for Natural Language Classifier.
-
-## Version 2.4.0
-_2018-06-12_
-* Regenerated SDK based on the latest API definition.
-* New: Support for Language Translator v3.
-* Fixed: Added a null header check in ErrorFilter.cs.
-* 
-## Version 2.3.0
-_2018-05-29_
-* Regenerated SDK based on the latest API definition. All services except for Natural Language Classifier support IAM authentication.
-* Service endpoint is set to the `gateway-a` endpoint if the user authenticates using apikey rather than TokenOptions.
-* Where a file is required we now use `FileStream` rather than `Stream` to preserve the filename.
-* New: Add `SetEndpoint()` method to the service base class. This sets a flag so we can keep track if the user manually changed the service endpoint and if so will not automatically change the endpoint.
-* Fixed: Disambiguate `IamUrl` and `ServiceUrl`. The `IamUrl` is now user configurable.
-
-## Version 2.2.2
-_2018-05-18_
-* Regenerated SDK based on latest API definition.
-* Fixed: Added in hand written sessions methods for Speech to Text ([#204](https://github.com/watson-developer-cloud/dotnet-standard-sdk/issues/204), [#205](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/205)).
-* Fixed: Revised type of `Timestamps` and `WordConfidence` in `SpeechRecognitionAlternative.cs` from `List<string>` to `string[][]` ([#198](https://github.com/watson-developer-cloud/dotnet-standard-sdk/issues/198), [#205](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/205)).
-* New: Revised tests to get credentials from our internal credential github repo([#4456](https://github.ibm.com/Watson/developer-experience/issues/4456), [#215](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/215)).
-* New: Support for IAM authentication ([#4288](https://zenhub.innovate.ibm.com/app/workspace/o/watson/developer-experience/issues/4288), [#210](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/210)).
-
-## Version 2.2.1
-_2018-04-21_
-* New: Support for custom request and response headers ([#4311](https://github.ibm.com/Watson/developer-experience/issues/4311), [#206](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/206)).
-
-## Version 2.2.0
-_2018-04-09_
-* New: Updated Visual Recognition with Core ML support ([4181](https://zenhub.innovate.ibm.com/app/workspace/o/watson/developer-experience/issues/4181), [201](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/201)).
-* New: Added Classify Collection to the Natural Language Classifier ([4224](https://zenhub.innovate.ibm.com/app/workspace/o/watson/developer-experience/issues/4224), [199](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/199)).
-* Fixed: Added Readme for Assistant, revised service readme files to add VersionDate when instantiating and revise service readme to use .csproj instead of project.json. ([194](https://github.com/watson-developer-cloud/dotnet-standard-sdk/issues/194), [195](https://github.com/watson-developer-cloud/dotnet-standard-sdk/pull/195)).
-
-## Version 2.1.0
-_2018-03-16_
-* New: Generate Watson Assistant.
-* Fixed: Text to Speech Synthesize method sends accept via query parameter instead of header.
-
-## Version 2.0.0
-_2018-03-09_
-* Breaking Change: Migrate to Visual Studio 2017.
-* Breaking Change: Regenerate all services using latest code generator & templates.
-* New: Revised integration tests.
-* New: Added documentation about publishing a release.
-* New: Generate Speech to Text service.
-* New: Generate Text to Speech service.
-* New: Generate Natural Language Classifier service.
-* New: Generate Visual Recognition service.
-
-## Version 1.3.1
-_2018-01-09_
-* Fix: Change `Context` in `MessageRequest` to `dynamic`.
-
-## Version 1.3.0
-_2018-01-07_
-* New: Generate Language Translator service.
-* Fix: Update Visual Recognition service to reflect API changes.
-* New: Use credential service for testing credentials.
-
-## Version 1.2.0
-_2017-07-18_
-* Fix: Update input and context in MessageRequest and MessageResponse for `Conversation` to be dynamic.
-* Fix: Changes in error handling to check if return error is a string or json object.
-* New: Conversation example showing messaging with conversation context.
-
-## Version 1.1.0
-_2017-06-30_
-* Fix: Include support for Xamarin Android, Xamarin iOS and .NET Core App (4.6>).
-
-## Version 1.0.0
-_2017-06_19_
-* Breaking Change: Refactor SDK to integrate generated services including adding service version to the package namespace.
-* New: Generate services for `Personality Insights`, `Tone Analyzer`, `Conversation`, `Natural Language Understanding` and `Discovery` via Swagger Codegen.
-* Integration and unit test for all generated services.
-
-## Version 0.2.0
-_2017-04-25_
-
-* New: Abstracted `Visual Recognition` service.
-* New: Completed `Speech to Text` abstraction.
-* New: Completed `Conversation` abstraction.
-* New: Integration and Unit tests.
-* New: Example service calls.
-* Fix: Enabled fail build on failed test in AppVeyor.
-* Fix: Fixed all integration and unit tests.
-
-## Version 0.1.0-alpha
-_2017-02-12_
-
-Initial alpha release of .NET Standard SDK. Service supported include:
-* Conversation
-* Speech to Text
-* Text to Speech
-* Language Translator
-* Personality Insights
-* Tone Analyzer
+Moved to [https://github.com/watson-developer-cloud/dotnet-standard-sdk/wiki/Change-Log](https://github.com/watson-developer-cloud/dotnet-standard-sdk/wiki/Change-Log)

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Watson Developer Cloud .NET Standard SDK"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.4.1
+PROJECT_NUMBER         = 2.4.2
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

README.md

@@ -17,7 +17,7 @@ The .Net SDK uses the [Watson Developer Cloud][wdc] services, a collection of RE
 ## Before you begin
 Ensure you have the following prerequisites:
 
-* An IBM Cloud account. If you don't have one, [sign up][bluemix_registration].
+* You need an [IBM Cloud][ibm-cloud-onboarding] account.
 * Install [Visual Studio][visual-studio-download] for Windows or [Visual Studio Code][visual-studio-code-download] for OSX or Linux.
 * Install [.NET Core][dotnet-core-download].
 
@@ -27,7 +27,7 @@ You can get the latest SDK packages through NuGet. Installation instructions can
 * [Assistant](/src/IBM.WatsonDeveloperCloud.Assistant.v1)
 * [Conversation](/src/IBM.WatsonDeveloperCloud.Conversation.v1)
 * [Discovery](/src/IBM.WatsonDeveloperCloud.Discovery.v1)
-* [Language Translator V2](/src/IBM.WatsonDeveloperCloud.LanguageTranslator.v2)
+* [Language Translator V2](/src/IBM.WatsonDeveloperCloud.LanguageTranslator.v2) (deprecated)
 * [Language Translator V3](/src/IBM.WatsonDeveloperCloud.LanguageTranslator.v3)
 * [Natural Language Understanding](/src/IBM.WatsonDeveloperCloud.NaturalLanguageUnderstanding.v1)
 * [Natural Language Classifier](/src/IBM.WatsonDeveloperCloud.NaturalLanguageClassifier.v1)
@@ -39,6 +39,76 @@ You can get the latest SDK packages through NuGet. Installation instructions can
 
 Or manually [here][latest_release].
 
+## Authentication
+Watson services are migrating to token-based Identity and Access Management (IAM) authentication.
+
+- With some service instances, you authenticate to the API by using **[IAM](#iam)**.
+- In other instances, you authenticate by providing the **[username and password](#username-and-password)** for the service instance.
+- Visual Recognition uses a form of [API key](#api-key) only with instances created before May 23, 2018. Newer instances of Visual Recognition use [IAM](#iam).
+
+### Getting credentials
+To find out which authentication to use, view the service credentials. You find the service credentials for authentication the same way for all Watson services:
+
+1.  Go to the IBM Cloud **[Dashboard][watson-dashboard]** page.
+1.  Either click an existing Watson service instance or click **Create**.
+1.  Click **Show** to view your service credentials.
+1.  Copy the `url` and either `apikey` or `username` and `password`.
+
+In your code, you can use these values in the service constructor or with a method call after instantiating your service.
+
+### IAM
+
+Some services use token-based Identity and Access Management (IAM) authentication. IAM authentication uses a service API key to get an access token that is passed with the call. Access tokens are valid for approximately one hour and must be regenerated.
+
+You supply either an IAM service **API key** or an **access token**:
+
+- Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
+- Use the access token if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://console.bluemix.net/docs/services/watson/getting-started-iam.html). If you want to switch to API key override your stored IAM credentials with an IAM API key.
+
+#### Supplying the IAM API key
+```cs
+void Example()
+{
+    TokenOptions iamAssistantTokenOptions = new TokenOptions()
+    {
+        IamApiKey = "<iam-apikey>",
+        IamUrl = "<service-endpoint>"
+    };
+
+    _assistant = new AssistantService(iamAssistantTokenOptions, "<version-date>");
+}
+```
+
+#### Supplying the access token
+```cs
+void Example()
+{
+    TokenOptions iamAssistantTokenOptions = new TokenOptions()
+    {
+        IamAccessToken = "<iam-access-token>"
+    };
+
+    _assistant = new AssistantService(iamAssistantTokenOptions, "<version-date>");
+}
+```
+
+### Username and password
+```cs
+void Example()
+{
+    _assistant = new AssistantService("<username>", "<password>", "<version-date>");
+}
+```
+
+### API key
+**Important**: This type of authentication works only with Visual Recognition instances created before May 23, 2018. Newer instances of Visual Recognition use [IAM](#iam).
+```cs
+void Example()
+{
+    _visualRecognition = new VisualRecognitionService("<apikey>", "<version-date>");
+}
+```
+
 ## Custom Request Headers
 You can send custom request headers by adding them to the `customData` object.
 ```cs
@@ -72,24 +142,6 @@ void Example()
 }
 ```
 
-## IAM Authentication
-You can authenticate using IAM rather than username and password or apikey. You can either allow the SDK to manage the token by providing your IAM apikey or manage the token yourself by providing an access token.
-```cs
-void Example()
-{
-    //  Provide either an iamApiKey or iamAccessToken to authenticate the service.
-    TokenOptions iamAssistantTokenOptions = new TokenOptions()
-    {
-        IamApiKey = "<iam-apikey>",
-        IamAccessToken = "<iam-access-token>",
-        IamUrl = "<service-endpoint>"
-    };
-
-    _assistant = new AssistantService(iamAssistantTokenOptions, "<version-date>");
-    var results = assistant.Message("<workspace-id>", "<message-request>");
-}
-```
-
 ## Documentation
 Click [here][dotnet-standard-sdk-documentation] for documentation by release and branch.
 
@@ -135,3 +187,4 @@ See [CONTRIBUTING.md](.github/CONTRIBUTING.md).<TODO revise coding standard>
 [visual-studio-download]: https://www.visualstudio.com/vs/community/
 [visual-studio-code-download]: https://code.visualstudio.com/
 [dotnet-standard-sdk-documentation]: https://watson-developer-cloud.github.io/dotnet-standard-sdk/
+[ibm-cloud-onboarding]: http://console.bluemix.net/registration?target=/developer/watson&cm_sp=WatsonPlatform-WatsonServices-_-OnPageNavLink-IBMWatson_SDKs-_-DotNet

examples/IBM.WatsonDeveloperCloud.Conversation.v1.Example/IBM.WatsonDeveloperCloud.Conversation.v1.Example.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionPrefix>2.4.1</VersionPrefix>
+    <VersionPrefix>2.4.2</VersionPrefix>
     <TargetFramework>netcoreapp1.0</TargetFramework>
     <AssemblyName>IBM.WatsonDeveloperCloud.Conversation.v1.Example</AssemblyName>
     <OutputType>Exe</OutputType>
@@ -10,7 +10,7 @@
     <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
     <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <Version>2.4.1</Version>
+    <Version>2.4.2</Version>
   </PropertyGroup>
 
   <ItemGroup>

examples/IBM.WatsonDeveloperCloud.Discovery.v1.Example/IBM.WatsonDeveloperCloud.Discovery.v1.Example.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionPrefix>2.4.1</VersionPrefix>
+    <VersionPrefix>2.4.2</VersionPrefix>
     <TargetFramework>netcoreapp1.0</TargetFramework>
     <AssemblyName>IBM.WatsonDeveloperCloud.Discovery.v1.Example</AssemblyName>
     <OutputType>Exe</OutputType>
@@ -10,7 +10,7 @@
     <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
     <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <Version>2.4.1</Version>
+    <Version>2.4.2</Version>
   </PropertyGroup>
 
   <ItemGroup>

examples/IBM.WatsonDeveloperCloud.LanguageTranslator.v2.Example/IBM.WatsonDeveloperCloud.LanguageTranslator.v2.Example.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionPrefix>2.4.1</VersionPrefix>
+    <VersionPrefix>2.4.2</VersionPrefix>
     <TargetFramework>netcoreapp1.0</TargetFramework>
     <AssemblyName>IBM.WatsonDeveloperCloud.LanguageTranslator.v2.Example</AssemblyName>
     <OutputType>Exe</OutputType>
@@ -10,7 +10,7 @@
     <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
     <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <Version>2.4.1</Version>
+    <Version>2.4.2</Version>
   </PropertyGroup>
 
   <ItemGroup>

examples/IBM.WatsonDeveloperCloud.LanguageTranslator.v3.Example/IBM.WatsonDeveloperCloud.LanguageTranslator.v2.Example.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionPrefix>2.4.1</VersionPrefix>
+    <VersionPrefix>2.4.2</VersionPrefix>
     <TargetFramework>netcoreapp1.0</TargetFramework>
     <AssemblyName>IBM.WatsonDeveloperCloud.LanguageTranslator.v3.Example</AssemblyName>
     <OutputType>Exe</OutputType>
@@ -10,7 +10,7 @@
     <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
     <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <Version>2.4.1</Version>
+    <Version>2.4.2</Version>
   </PropertyGroup>
 
   <ItemGroup>

examples/IBM.WatsonDeveloperCloud.NaturalLanguageUnderstanding.v1.Ex/IBM.WatsonDeveloperCloud.NLU.v1.Example.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionPrefix>2.4.1</VersionPrefix>
+    <VersionPrefix>2.4.2</VersionPrefix>
     <TargetFramework>netcoreapp1.0</TargetFramework>
     <AssemblyName>IBM.WatsonDeveloperCloud.NaturalLanguageUnderstanding.v1.Ex</AssemblyName>
     <OutputType>Exe</OutputType>
@@ -10,7 +10,7 @@
     <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
     <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <Version>2.4.1</Version>
+    <Version>2.4.2</Version>
   </PropertyGroup>
 
   <ItemGroup>

examples/IBM.WatsonDeveloperCloud.PersonalityInsights.v3.Example/IBM.WatsonDeveloperCloud.PersonalityInsights.v3.Example.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionPrefix>2.4.1</VersionPrefix>
+    <VersionPrefix>2.4.2</VersionPrefix>
     <TargetFramework>netcoreapp1.0</TargetFramework>
     <AssemblyName>IBM.WatsonDeveloperCloud.PersonalityInsights.v3.Example</AssemblyName>
     <OutputType>Exe</OutputType>
@@ -10,7 +10,7 @@
     <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
     <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <Version>2.4.1</Version>
+    <Version>2.4.2</Version>
   </PropertyGroup>
 
   <ItemGroup>

examples/IBM.WatsonDeveloperCloud.SpeechToText.v1.Example/IBM.WatsonDeveloperCloud.SpeechToText.v1.Example.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <VersionPrefix>2.4.1</VersionPrefix>
+    <VersionPrefix>2.4.2</VersionPrefix>
     <TargetFramework>netcoreapp1.0</TargetFramework>
     <AssemblyName>IBM.WatsonDeveloperCloud.SpeechToText.v1.Example</AssemblyName>
     <OutputType>Exe</OutputType>
@@ -10,7 +10,7 @@
     <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
     <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
     <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <Version>2.4.1</Version>
+    <Version>2.4.2</Version>
   </PropertyGroup>
 
   <ItemGroup>