diff --git a/website/docs/sdks/dot_net.md b/website/docs/sdks/dot_net.md index e7046a2729..139c4a6313 100644 --- a/website/docs/sdks/dot_net.md +++ b/website/docs/sdks/dot_net.md @@ -3,6 +3,8 @@ id: dot_net_sdk title: .NET SDK --- +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + In this guide we explain how to use feature toggles in a .NET application using Unleash-hosted. We will be using the open source Unleash [.net Client SDK](https://github.com/Unleash/unleash-client-dotnet). > You will need your `API URL` and your `API token` in order to connect the Client SDK to you Unleash instance. You can find this information in the “Admin” section Unleash management UI. [Read more](../user_guide/api-token) @@ -19,6 +21,19 @@ dotnet add package unleash.client Next we must initialize a new instance of the Unleash Client. +:::tip Synchronous initialization + +By default, the client SDK asynchronously fetches toggles from the Unleash API on initialization. This means it can take a few hundred milliseconds for the client to reach the correct state. + +You can use the `synchronousInitialization` option of the `UnleashClientFactory` class's `CreateClientAsync` method to block the client until it has successfully synced with the server. See the following "synchronous initialization" code sample. + +Read more about the [Unleash architecture](https://www.getunleash.io/blog/our-unique-architecture) to learn how it works. + +::: + + + + ```csharp var settings = new UnleashSettings() { @@ -34,6 +49,31 @@ var settings = new UnleashSettings() IUnleash unleash = new DefaultUnleash(settings); ``` + + + +```csharp +var settings = new UnleashSettings() +{ + AppName = "dot-net-client", + Environment = "local", + UnleashApi = new Uri("API URL"), + CustomHttpHeaders = new Dictionary() + { + {"Authorization","API token" } + } +}; + +var unleashFactory = new UnleashClientFactory(); + +// this `unleash` will fetch feature toggles and write them to its cache before returning from the await call. +// if network errors or disk permissions prevent this from happening, the await will throw an exception. +IUnleash unleash = await unleashFactory.CreateClientAsync(settings, synchronousInitialization: true); +``` + + + + In your app you typically just want one instance of Unleash, and inject that where you need it. You should change the URL and the Authorization header (API token) with the correct values for your instance, which you may locate under “Instance admin” in the menu. @@ -53,10 +93,6 @@ else } ``` -Please note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the _SynchronousInitialization_ option to block the client until it has successfully synced with the server. - -Read more about the [Unleash architecture](https://www.getunleash.io/blog/our-unique-architecture) to learn how it works in more details - ## Step 4: Provide Unleash Context {#step-4-provide-unleash-context} It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the activation strategies, which are implemented in the client SDK. diff --git a/website/docs/sdks/java.md b/website/docs/sdks/java.md index f004b2756b..e7087a5298 100644 --- a/website/docs/sdks/java.md +++ b/website/docs/sdks/java.md @@ -3,6 +3,8 @@ id: java_sdk title: Java SDK --- +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + In this guide we explain how to use feature toggles in a Java application using Unleash-hosted. We will be using the open source Unleash [Java Client SDK](https://github.com/Unleash/unleash-client-java). > You will need your `API URL` and your `API token` in order to connect the Client SDK to you Unleash instance. You can find this information in the “Admin” section Unleash management UI. [Read more](../user_guide/api-token) @@ -23,6 +25,15 @@ First we must add Unleash Client SDK as a dependency to your project. Below is a Next we must initialize a new instance of the Unleash Client. +:::tip Synchronous initialization + +The client SDK will synchronize with the Unleash API on initialization, so it can take a few hundred milliseconds for the client to reach the correct state. You can use the `synchronousFetchOnInitialisation` option to block the client until it has successfully synced with the server. + +::: + + + + ```java UnleashConfig config = UnleashConfig.builder() .appName("my.java-app") @@ -35,6 +46,25 @@ UnleashConfig config = UnleashConfig.builder() Unleash unleash = new DefaultUnleash(config); ``` + + + +```java +UnleashConfig config = UnleashConfig.builder() + .appName("my.java-app") + .instanceId("your-instance-1") + .environment(System.getenv("APP_ENV")) + .unleashAPI("API URL") + .customHttpHeader("Authorization", "API token") + .synchronousFetchOnInitialization(true) + .build(); + +Unleash unleash = new DefaultUnleash(config); +``` + + + + In your app you typically just want one instance of Unleash, and inject that where you need it. You will typically use a dependency injection frameworks such as Spring or Guice to manage this. You should change the URL and the Authorization header (API token) with the correct values for your instance, which you may locate under “Instance admin” in the menu. @@ -51,8 +81,6 @@ if(unleash.isEnabled("AwesomeFeature")) { } ``` -Please note the client SDK will synchronize with the Unleash-hosted API on initialization, and thus it can take a few milliseconds the first time before the client has the correct state. You can use the _synchronousFetchOnInitialisation_ option to block the client until it has successfully synced with the server. - Read more about the [Unleash architecture](https://www.unleash-hosted.com/articles/our-unique-architecture) to learn how it works in more details ## Step 4: Provide Unleash Context {#step-4-provide-unleash-context} diff --git a/website/docs/sdks/node.md b/website/docs/sdks/node.md index 8c1470a5e8..1b29f954f0 100644 --- a/website/docs/sdks/node.md +++ b/website/docs/sdks/node.md @@ -3,6 +3,8 @@ id: node_sdk title: Node SDK --- +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; + In this guide we explain how to use feature toggles in a Node application using Unleash-hosted. We will be using the open source Unleash [Node.js Client SDK](https://github.com/Unleash/unleash-client-node). > You will need your `API URL` and your `API token` in order to connect the Client SDK to you Unleash instance. You can find this information in the “Admin” section Unleash management UI. [Read more](../user_guide/api-token) @@ -19,6 +21,17 @@ npm install unleash-client Next we must initialize the client SDK in the application: +:::tip Synchronous initialization + +The client SDK will synchronize with the Unleash API on initialization, so it can take a few hundred milliseconds for the client to reach the correct state. + +See the following code sample or the [_block until Unleash is synchronized_ section of the readme](https://github.com/Unleash/unleash-client-node#block-until-unleash-sdk-has-synchronized) for the steps to do this. + +::: + + + + ```js const unleash = require('unleash-client'); @@ -30,9 +43,24 @@ unleash.initialize({ }); ``` -The example code above will initialize the client SDK, and connect to the Unleash-hosted demo instance. It also uses the API token for the demo instance. You should change the URL and the Authorization header (API token) with the correct values for your instance, which you may locate under “Instance admin” in the menu. + + -Please also pay attention to the “environment” option. Setting this will allow you to use [strategy constraints](/advanced/strategy_constraints) which enables different roll-out strategies per environment. +```js +const { startUnleash } = require('unleash-client'); + +const unleash = await startUnleash({ + url: 'https://YOUR-API-URL', + appName: 'my-node-name', + environment: process.env.APP_ENV, + customHeaders: { Authorization: 'SOME-SECRET' }, +}); +``` + + + + +The example code above will initialize the client SDK, and connect to the Unleash-hosted demo instance. It also uses the API token for the demo instance. You should change the URL and the Authorization header (API token) with the correct values for your instance, which you may locate under “Instance admin” in the menu. ## Step 3: Use the feature toggle {#step-3-use-the-feature-toggle} @@ -52,7 +80,7 @@ Please note that in the above example we put the isEnabled-evaluation inside the It can also be nice to notice that if you use an undefined feature toggle the Unleash SDK will return false instead of crashing your application. The SDK will also report metrics back to Unleash-hosted on feature toggle usage, which makes it \_possible to spot toggles not yet defined. And this is a very neat way to help you debug if something does not work as expected. -_Note that you can also wait until the Unleash SDK has fully syncrhonized similar to familiar "on-ready" hooks in other APIs. See [block until Unleashed is synchronized](https://github.com/Unleash/unleash-client-node#block-until-unleash-sdk-has-synchronized) for how to do this._ +_Note that you can also wait until the Unleash SDK has fully synchronized similar to familiar "on-ready" hooks in other APIs. See [block until Unleashed is synchronized](https://github.com/Unleash/unleash-client-node#block-until-unleash-sdk-has-synchronized) for how to do this._ ## Step 4: Provide the Unleash-context {#step-4-provide-the-unleash-context}