From 993f25b34f72650fa9d2fcbd3ffaf1f2c6060d70 Mon Sep 17 00:00:00 2001 From: Adam Simon Date: Wed, 31 Jul 2024 16:58:51 +0200 Subject: [PATCH 1/6] Add documentation for custom log filter --- website/docs/sdk-reference/dotnet.mdx | 25 +++++++++++++++++++++++-- website/docs/sdk-reference/java.mdx | 17 ++++++++++------- 2 files changed, 33 insertions(+), 9 deletions(-) diff --git a/website/docs/sdk-reference/dotnet.mdx b/website/docs/sdk-reference/dotnet.mdx index 286702b3..ca881124 100644 --- a/website/docs/sdk-reference/dotnet.mdx +++ b/website/docs/sdk-reference/dotnet.mdx @@ -104,11 +104,12 @@ These are the available options on the `ConfigCatClientOptions` class: | `PollingMode` | Optional, sets the polling mode for the client. [More about polling modes](#polling-modes). | `PollingModes.AutoPoll()` | | `ConfigCache` | Optional, [`IConfigCatCache`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Cache/IConfigCatCache.cs) instance for caching the downloaded config. | [`InMemoryConfigCache`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Cache/InMemoryConfigCache.cs) | | `Logger` | Optional, [`IConfigCatLogger`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Logging/IConfigCatLogger.cs) instance for tracing. | [`ConsoleLogger`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Logging/ConsoleLogger.cs) (with WARNING level) | +| `LogFilter` | Optional, sets a custom log filter. [More about log filtering](#log-filtering). | `null` (none) | | `BaseUrl` | Optional, sets the CDN base url (forward proxy, dedicated subscription) from where the SDK will download the config JSON. | | -| `HttpClientHandler` | Optional, `HttpClientHandler` to provide network credentials and proxy settings. [More about the proxy settings](#using-configcat-behind-a-proxy). | built-in `HttpClientHandler` | +| `HttpClientHandler` | Optional, `HttpClientHandler` to provide network credentials and proxy settings. [More about the proxy settings](#using-configcat-behind-a-proxy). | built-in `HttpClientHandler` | | `HttpTimeout` | Optional, sets the underlying HTTP client's timeout. [More about the HTTP timeout](#http-timeout). | `TimeSpan.FromSeconds(30)` | | `FlagOverrides` | Optional, sets the local feature flag & setting overrides. [More about feature flag overrides](#flag-overrides). | | -| `DataGovernance` | Optional, defaults to `Global`. Describes the location of your feature flag and setting data within the ConfigCat CDN. This parameter needs to be in sync with your Data Governance preferences. [More about Data Governance](../advanced/data-governance.mdx). Available options: `Global`, `EuOnly` | `Global` | +| `DataGovernance` | Optional, defaults to `Global`. Describes the location of your feature flag and setting data within the ConfigCat CDN. This parameter needs to be in sync with your Data Governance preferences. [More about Data Governance](../advanced/data-governance.mdx). Available options: `Global`, `EuOnly` | `Global` | | `DefaultUser` | Optional, sets the default user. [More about default user](#default-user). | `null` (none) | | `Offline` | Optional, determines whether the client should be initialized to offline mode. [More about offline mode](#online--offline-mode). | `false` | @@ -703,10 +704,30 @@ ConfigCat.INFO [5000] Evaluating 'isPOCFeatureEnabled' for User '{"Identifier": Returning 'True'. ``` +### Custom logger implementation + +By default, the SDK logs to [the console's standard output](https://learn.microsoft.com/en-us/dotnet/api/system.console.out) but it also allows you to inject any custom logger implementation via the `ConfigCatClientOptions.Logger` property. + Sample code on how to create a basic file logger implementation for ConfigCat client: See Sample Code Another sample which shows how to implement an adapter to [the built-in logging framework](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/logging) of .NET Core/.NET 5+: See Sample Code +### Log Filtering + +You can define a custom log filter by providing a callback function via the `ConfigCatClientOptions.LogFilter` property. The callback will be called by the _ConfigCat SDK_ each time a log event occurs (and the event passes the minimum log level specified by the `IConfigCatLogger.LogLevel` property). That is, the callback allows you to filter log events by `level`, `eventId`, `message` or `exception`. The formatted message string can be obtained via `message.InvariantFormattedMessage`. +If the callback function returns `true`, the event will be logged, otherwise it will be skipped. + +```cs +// Filter out events with id 1001 from the log. +LogFilterCallback logFilter = (LogLevel level, LogEventId eventId, ref FormattableLogMessage message, Exception? exception) => eventId != 1001; + +var client = ConfigCatClient.Get("#YOUR-SDK-KEY#", options => options.LogFilter = logFilter); +``` + +:::caution +Please make sure that your log filter logic doesn't perform heavy computation and doesn't block the executing thread. A complex or incorrectly implemented log filter can degrade the performance of the SDK. +::: + ## `GetAllKeysAsync()` You can get all the setting keys from your configuration by calling the `GetAllKeysAsync()` method of the `ConfigCatClient`. diff --git a/website/docs/sdk-reference/java.mdx b/website/docs/sdk-reference/java.mdx index 00505383..9fbb3edb 100644 --- a/website/docs/sdk-reference/java.mdx +++ b/website/docs/sdk-reference/java.mdx @@ -119,11 +119,11 @@ These are the available options on the `Options` class: | `cache(ConfigCache)` | Optional, sets a custom cache implementation for the client. [More about cache](#custom-cache). | | `pollingMode(PollingMode)` | Optional, sets the polling mode for the client. [More about polling modes](#polling-modes). | | `logLevel(LogLevel)` | Optional, defaults to `WARNING`. Sets the internal log level. [More about logging](#logging). | +| `logFilter(LogFilterFunction)` | Optional, sets a custom log filter. [More about log filtering](#log-filtering). | | `flagOverrides(OverrideDataSourceBuilder, OverrideBehaviour)` | Optional, sets the local feature flag & setting overrides. [More about feature flag overrides](#flag-overrides). | | `defaultUser(User)` | Optional, sets default user. [More about default user](#default-user). | | `offline(boolean)` | Optional, defaults to `false`. Indicates whether the SDK should be initialized in offline mode. [More about offline mode](#online--offline-mode). | | `hooks()` | Optional, used to subscribe events that the SDK sends in specific scenarios. [More about hooks](#hooks). | -| `logFilter(LogFilterFunction)` | Optional, sets a custom log filter. [More about log filtering](#log-filtering). | :::caution We strongly recommend you to use the `ConfigCatClient` as a Singleton object in your application. @@ -874,16 +874,19 @@ Examples fo options.logFilter(filterLogFunction)); +ConfigCatClient client = ConfigCatClient.get("#YOUR-SDK-KEY#", options -> options.logFilter(filterLogFunction)); ``` -> Please make sure that your log filter logic doesn't perform heavy computation and doesn't block the executing thread. A complex or incorrectly implemented log filter can degrade the performance of the SDK. + +:::caution +Please make sure that your log filter logic doesn't perform heavy computation and doesn't block the executing thread. A complex or incorrectly implemented log filter can degrade the performance of the SDK. +::: ## Sample Apps From 52a2d6d4232e8abe6159981d83301fc06199e334 Mon Sep 17 00:00:00 2001 From: Adam Simon Date: Wed, 31 Jul 2024 18:42:38 +0200 Subject: [PATCH 2/6] Add docs on platform compatibility --- website/docs/sdk-reference/dotnet.mdx | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/website/docs/sdk-reference/dotnet.mdx b/website/docs/sdk-reference/dotnet.mdx index ca881124..b1f82509 100644 --- a/website/docs/sdk-reference/dotnet.mdx +++ b/website/docs/sdk-reference/dotnet.mdx @@ -102,6 +102,7 @@ These are the available options on the `ConfigCatClientOptions` class: | Properties | Description | Default | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `PollingMode` | Optional, sets the polling mode for the client. [More about polling modes](#polling-modes). | `PollingModes.AutoPoll()` | +| `ConfigFetcher` | Optional, [`IConfigCatConfigFetcher`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/ConfigService/IConfigCatConfigFetcher.cs) instance for downloading a config. | [`HttpClientConfigFetcher`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/ConfigService/HttpClientConfigFetcher.cs) | | `ConfigCache` | Optional, [`IConfigCatCache`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Cache/IConfigCatCache.cs) instance for caching the downloaded config. | [`InMemoryConfigCache`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Cache/InMemoryConfigCache.cs) | | `Logger` | Optional, [`IConfigCatLogger`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Logging/IConfigCatLogger.cs) instance for tracing. | [`ConsoleLogger`](https://github.com/configcat/.net-sdk/blob/master/src/ConfigCatClient/Logging/ConsoleLogger.cs) (with WARNING level) | | `LogFilter` | Optional, sets a custom log filter. [More about log filtering](#log-filtering). | `null` (none) | @@ -891,6 +892,23 @@ IConfigCatClient client = ConfigCatClient.Get("#YOUR-SDK-KEY#", options => The default timeout is 30 seconds. +## Platform compatibility + +The _ConfigCat SDK_ supports all the widespread .NET JIT runtimes, everything that implements [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0)+ should work. +Starting with v9.3.0, it can also be used in applications that employ [trimmed self-contained](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained) or various ahead-of-time (AOT) compilation deployment models. + +The SDK has been tested on the following .NET runtimes: +* .NET Framework 4.5+ +* .NET Core 3.1, .NET 5+ +* .NET 8 Native AOT +* UWP/WinUI (.NET MAUI 8) +* Mono JIT (Unity 2021.3+) +* Mono AOT (.NET MAUI 8 iOS) +* Mono WebAssembly AOT/Emscripten (ASP.NET Core Blazor 8) +* IL2CPP (Unity 2021.3+) - Unity WebGL also works but needs a bit of extra effort (see [sample scripts](https://github.com/configcat/.net-sdk/tree/master/samples/UnityWebGL)) + +We strive to provide an extensive support for the various .NET runtimes and versions. If you still encounter an issue with the SDK on some platform, please open a [GitHub issue](https://github.com/configcat/.net-sdk/issues/new/choose) or contact support. + ## Troubleshooting When the _ConfigCat SDK_ does not work as expected in your application, please check for the following potential problems: @@ -925,7 +943,9 @@ When the _ConfigCat SDK_ does not work as expected in your application, please c Check out our Sample Applications how they use the _ConfigCat SDK_: - Sample Console App -- Sample Web App +- Sample Multi-page Web App (ASP.NET Core MVC) +- Sample Single-page Web App (ASP.NET Core Blazor) +- Sample Mobile/Windows Store App (.NET MAUI) ## Guides From fc81ef05209e73a0f3e350d752bb804975f29c10 Mon Sep 17 00:00:00 2001 From: Adam Simon Date: Fri, 2 Aug 2024 19:51:40 +0200 Subject: [PATCH 3/6] Corrections to "Platform compatibility" --- website/docs/sdk-reference/dotnet.mdx | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/website/docs/sdk-reference/dotnet.mdx b/website/docs/sdk-reference/dotnet.mdx index b1f82509..405432dd 100644 --- a/website/docs/sdk-reference/dotnet.mdx +++ b/website/docs/sdk-reference/dotnet.mdx @@ -894,18 +894,23 @@ The default timeout is 30 seconds. ## Platform compatibility -The _ConfigCat SDK_ supports all the widespread .NET JIT runtimes, everything that implements [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0)+ should work. +The _ConfigCat SDK_ supports all the widespread .NET JIT runtimes, everything that implements [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0)+ and supports TLS 1.2 should work. Starting with v9.3.0, it can also be used in applications that employ [trimmed self-contained](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained) or various ahead-of-time (AOT) compilation deployment models. -The SDK has been tested on the following .NET runtimes: -* .NET Framework 4.5+ -* .NET Core 3.1, .NET 5+ -* .NET 8 Native AOT -* UWP/WinUI (.NET MAUI 8) -* Mono JIT (Unity 2021.3+) -* Mono AOT (.NET MAUI 8 iOS) -* Mono WebAssembly AOT/Emscripten (ASP.NET Core Blazor 8) -* IL2CPP (Unity 2021.3+) - Unity WebGL also works but needs a bit of extra effort (see [sample scripts](https://github.com/configcat/.net-sdk/tree/master/samples/UnityWebGL)) +Based on our tests, the SDK is compatible with the following runtimes/deployment models: +* .NET Framework 4.5+ (including Ngen) +* .NET Core 3.1, .NET 5+ (including Crossgen2/ReadyToRun and Native AOT) +* Mono 5.10+ +* .NET for Android (formerly known as Xamarin.Android) +* .NET for iOS (formerly known as Xamarin.iOS) +* Unity 2021.3+ (Mono JIT) +* Unity 2021.3+ (IL2CPP)* +* Universal Windows Platform 10.0.16299.0+ (.NET Native)** +* WebAssembly (Mono AOT/Emscripten, also known as wasm-tools) + +*Unity WebGL also works but needs a bit of extra effort: you will need to enable WebGL compatibility by calling the `ConfigCatClient.PlatformCompatibilityOptions.EnableUnityWebGLCompatibility` method. For more details, see [Sample Scripts](https://github.com/configcat/.net-sdk/tree/master/samples/UnityWebGL). +
+**To make the SDK work in Release builds on UWP, you will need to add `` to your application's [.rd.xml](https://learn.microsoft.com/en-us/windows/uwp/dotnet-native/runtime-directives-rd-xml-configuration-file-reference) file. See also [this discussion](https://github.com/dotnet/runtime/issues/29912#issuecomment-638471351). We strive to provide an extensive support for the various .NET runtimes and versions. If you still encounter an issue with the SDK on some platform, please open a [GitHub issue](https://github.com/configcat/.net-sdk/issues/new/choose) or contact support. From e06d25a4e6394b0e5a11f8a955ae3e30ebd21b85 Mon Sep 17 00:00:00 2001 From: Adam Simon Date: Fri, 2 Aug 2024 20:14:09 +0200 Subject: [PATCH 4/6] Fix formatting --- website/docs/sdk-reference/dotnet.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/docs/sdk-reference/dotnet.mdx b/website/docs/sdk-reference/dotnet.mdx index 405432dd..9c9583ef 100644 --- a/website/docs/sdk-reference/dotnet.mdx +++ b/website/docs/sdk-reference/dotnet.mdx @@ -908,8 +908,7 @@ Based on our tests, the SDK is compatible with the following runtimes/deployment * Universal Windows Platform 10.0.16299.0+ (.NET Native)** * WebAssembly (Mono AOT/Emscripten, also known as wasm-tools) -*Unity WebGL also works but needs a bit of extra effort: you will need to enable WebGL compatibility by calling the `ConfigCatClient.PlatformCompatibilityOptions.EnableUnityWebGLCompatibility` method. For more details, see [Sample Scripts](https://github.com/configcat/.net-sdk/tree/master/samples/UnityWebGL). -
+*Unity WebGL also works but needs a bit of extra effort: you will need to enable WebGL compatibility by calling the `ConfigCatClient.PlatformCompatibilityOptions.EnableUnityWebGLCompatibility` method. For more details, see [Sample Scripts](https://github.com/configcat/.net-sdk/tree/master/samples/UnityWebGL).
**To make the SDK work in Release builds on UWP, you will need to add `` to your application's [.rd.xml](https://learn.microsoft.com/en-us/windows/uwp/dotnet-native/runtime-directives-rd-xml-configuration-file-reference) file. See also [this discussion](https://github.com/dotnet/runtime/issues/29912#issuecomment-638471351). We strive to provide an extensive support for the various .NET runtimes and versions. If you still encounter an issue with the SDK on some platform, please open a [GitHub issue](https://github.com/configcat/.net-sdk/issues/new/choose) or contact support. From cab83119ca620bb1727a659a640e9419101081a2 Mon Sep 17 00:00:00 2001 From: Adam Simon Date: Wed, 28 Aug 2024 15:50:40 +0200 Subject: [PATCH 5/6] Minor correction --- website/docs/sdk-reference/dotnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/sdk-reference/dotnet.mdx b/website/docs/sdk-reference/dotnet.mdx index 9c9583ef..da467058 100644 --- a/website/docs/sdk-reference/dotnet.mdx +++ b/website/docs/sdk-reference/dotnet.mdx @@ -948,7 +948,7 @@ Check out our Sample Applications how they use the _ConfigCat SDK_: - Sample Console App - Sample Multi-page Web App (ASP.NET Core MVC) -- Sample Single-page Web App (ASP.NET Core Blazor) +- Sample Single-page Web App (ASP.NET Core Blazor WebAssembly) - Sample Mobile/Windows Store App (.NET MAUI) ## Guides From 1e8548df54b0f0fc604305211500fc8c9b53c733 Mon Sep 17 00:00:00 2001 From: Adam Simon Date: Wed, 28 Aug 2024 16:09:31 +0200 Subject: [PATCH 6/6] Add link --- website/docs/sdk-reference/dotnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/sdk-reference/dotnet.mdx b/website/docs/sdk-reference/dotnet.mdx index da467058..d15e87ac 100644 --- a/website/docs/sdk-reference/dotnet.mdx +++ b/website/docs/sdk-reference/dotnet.mdx @@ -895,7 +895,7 @@ The default timeout is 30 seconds. ## Platform compatibility The _ConfigCat SDK_ supports all the widespread .NET JIT runtimes, everything that implements [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0)+ and supports TLS 1.2 should work. -Starting with v9.3.0, it can also be used in applications that employ [trimmed self-contained](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained) or various ahead-of-time (AOT) compilation deployment models. +Starting with v9.3.0, it can also be used in applications that employ [trimmed self-contained](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained) or various [ahead-of-time (AOT) compilation](https://en.wikipedia.org/wiki/Ahead-of-time_compilation) deployment models. Based on our tests, the SDK is compatible with the following runtimes/deployment models: * .NET Framework 4.5+ (including Ngen)