Skip to content

Commit

Permalink
doc: readme update (#499)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Tr00d
Tr00d authored Sep 5, 2023
1 parent e40a432 commit 53c906d
Showing 1 changed file with 53 additions and 94 deletions.
147 changes: 53 additions & 94 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,11 @@ Sign up [for free at vonage.com][signup].
* [Tested frameworks](#tested-frameworks)
* [Configuration](#configuration)
* [Setup](#setup)
* [Provide credentials](#provide-credentials)
* [Service registration](#service-registration)
* [Set credentials in settings file](#set-credentials-in-settings-file)
* [Override values on Configuration singleton](#override-values-in-configuration-singleton)
* [Lazy registration (recommended for .NET Core and above)](#lazy-registration-recommended-for-net-core-and-above)
* [Manual initialization (recommended for .NET Framework)](#manual-initialization-recommended-for-net-framework)
* [Configuration reference](#configuration-reference)
* [Test configuration](#test-configuration)
* [Logging](#logging)
* [v5.0.0+](#v500-)
* [3.1.x, 5.0.0](#-31x-500-)
* [2.2.0, 3.0.x](#220---30x)
* [Monads](#monads)
* [Result](#result)
* [Maybe](#maybe)
Expand Down Expand Up @@ -108,32 +103,54 @@ Therefore, we ensure complete compatibility no matter the version you are using.

### Setup

To setup the configuration of the Vonage Client you can do one of the following.
There are various ways to initialize a `VonageClient` with your custom values.

### Provide credentials
Overall, we encourage you to specify your configuration (Vonage URLs, credentials, etc.) in `appsettings.json`, in an `appsettings` section:

Create a Vonage Client instance and pass in credentials in the constructor - this will only affect the security
credentials (Api Key, Api Secret, Signing Secret, Signing Method Private Key, App Id)
```json
{
"appSettings": {
"Vonage.UserAgent": "myApp/1.0",
"Vonage.Url.Rest": "https://rest.nexmo.com",
"Vonage.Url.Api": "https://api.nexmo.com",
"Vonage.Url.Api.Europe": "https://api-eu.vonage.com",
"Vonage.Url.Api.Video": "https://video.api.vonage.com",
"Vonage_key": "VONAGE-API-KEY",
"Vonage_secret": "VONAGE-API-SECRET",
"Vonage.Application.Id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"Vonage.Application.Key": "VONAGE_APPLICATION_PRIVATE_KEY"
}
}
```

```csharp
var credentials = Credentials.FromApiKeyAndSecret(
VONAGE_API_KEY,
VONAGE_API_SECRET
);
> Note: While the section is currently names `appsettings`, we intend to use a more explicit name like `vonageSettings`.
> Stay tuned for the next major release.
var vonageClient = new VonageClient(credentials);
```
The configuration is automatically loaded in the `Configuration` singleton.

### Service registration
#### Lazy registration (recommended for .NET Core and above)

You can also register a client in your `IServiceCollection` using the following extension methods:
> Note: This implementation is not available for .NET Framework usages, given IConfiguration has been introduced in .NET Core.
You can register a client in your `IServiceCollection` using the following extension methods:

- `AddVonageClientScoped`: registers using Scoped registration.
- `AddVonageClientTransient`: registers using Transient registration.

``` csharp
// For 'Scoped' lifecycle
builder.Services.AddVonageClientScoped(builder.Configuration);
// Foor 'Transient' lifecycle
builder.Services.AddVonageClientTransient(builder.Configuration);
```

> Note: Using `builder.Configuration` allow us to use settings you decided to load at runtime, including environment-specific settings.
``` csharp
var credentials = ...
// For 'Scoped' lifecycle
builder.Services.AddVonageClientScoped(credentials);
// or
// Foor 'Transient' lifecycle
builder.Services.AddVonageClientTransient(credentials);
```

Expand All @@ -145,32 +162,23 @@ It will register the main `VonageClient`, but also all sub client interfaces:
- IVoiceClient
- etc.

### Set credentials in settings file
Finally, you can inject them in any of your components.

Provide the vonage URLs, API key, secret, and application credentials (for JWT) in ```appsettings.json```:
#### Manual initialization (recommended for .NET Framework)

```json
{
"appSettings": {
"Vonage.UserAgent": "myApp/1.0",
"Vonage.Url.Rest": "https://rest.nexmo.com",
"Vonage.Url.Api": "https://api.nexmo.com",
"Vonage.Url.Api.Europe": "https://api-eu.vonage.com",
"Vonage.Url.Api.Video": "https://video.api.vonage.com",
"Vonage_key": "VONAGE-API-KEY",
"Vonage_secret": "VONAGE-API-SECRET",
"Vonage.Application.Id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"Vonage.Application.Key": "VONAGE_APPLICATION_PRIVATE_KEY"
}
}
```
Create a Vonage Client instance and pass in credentials in the constructor;
this will only affect the security credentials (Api Key, Api Secret, Signing Secret, Signing Method Private Key, App Id).

> Note: In the event multiple configuration files are found, the order of precedence is as follows:
> ```appsettings.json``` which overrides ```settings.json```
```csharp
var credentials = Credentials.FromApiKeyAndSecret(
VONAGE_API_KEY,
VONAGE_API_SECRET
);

### Override values in Configuration singleton
var vonageClient = new VonageClient(credentials);
```

Access the Configuration instance and set the appropriate key in your code for example:
If required, you can override values directly in the `Configuration` singleton:

```cshap
Configuration.Instance.Settings["appSettings:Vonage.Url.Api"] = "https://www.example.com/api";
Expand All @@ -179,7 +187,9 @@ Configuration.Instance.Settings["appSettings:Vonage.Url.Api.Europe"] = "https://
Configuration.Instance.Settings["appSettings:Vonage.Video.Url.Rest"] = "https://www.video.example.com/rest";
```

> NOTE: Private Key is the literal key - not a path to the file containing the key
> Note: Private Key is the literal key - not a path to the file containing the key
> Note: Modifying the Configuration instance will be deprecated in the upcoming release, to keep the configuration immutable.
### Configuration Reference

Expand Down Expand Up @@ -207,8 +217,6 @@ For security reasons, not RSA Private Key is hardcoded in the repository.

### Logging

#### v5.0.0 +

The Library uses Microsoft.Extensions.Logging to preform all of it's logging tasks. To configure logging for you app
simply create a new `ILoggerFactory` and call the `LogProvider.SetLogFactory()` method to tell the Vonage library how to
log. For example, to log to the console with serilog you can do the following:
Expand All @@ -228,55 +236,6 @@ factory.AddSerilog(log);
LogProvider.SetLogFactory(factory);
```

#### [3.1.x, 5.0.0)

The library makes use of [LibLog](https://github.com/damianh/LibLog/wiki) to facilitate logging.

Your application controls if and how logging occurs. Example using [Serilog](https://serilog.net/)
and [Serilog.Sinks.Console](https://www.nuget.org/packages/Serilog.Sinks.Console) v3.x:

```C#
using Vonage.Request;
using Serilog;

// set up logging at startup
var log = new LoggerConfiguration()
.MinimumLevel.Debug()
.WriteTo.Console(outputTemplate: "{Timestamp:HH:mm} [{Level}] ({Name:l}) {Message}")
.CreateLogger();
Log.Logger = log;

Log.Logger.Debug("start");
var client = new Vonage.VonageClient(new Credentials("example", "password"));
client.Account.GetBalance();
Log.Logger.Debug("end");
```

#### 2.2.0 - 3.0.x

You can request console logging by placing a ```logging.json``` file alongside your ```appsettings.json```
configuration.

Note that logging Vonage messages will very likely expose your key and secret to the console as they can be part of the
query string.

Example ```logging.json``` contents that would log all requests as well as major configuration and authentication
errors:

```json
{
"IncludeScopes": "true",
"LogLevel": {
"Default": "Debug",
"Vonage": "Debug",
"Vonage.Authentication": "Error",
"Vonage.Configuration": "Error"
}
}
```

You may specify other types of logging (file, etc.).

## Monads

Most recent features expose responses/results
Expand Down

0 comments on commit 53c906d

Please sign in to comment.