diff --git a/README.md b/README.md index 00fa735..8b54b11 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

FiddlerCore Public Documentation

-

Welcome to the GitHub repo for FiddlerCore Documentation. This repository contains the source content--written in Markdown--that we use to power the FiddlerCore. +

Welcome to the GitHub repo for FiddlerCore Documentation. This repository contains the source content--written in Markdown--that we use to power the FiddlerCore documentation.

We believe that the documentation for a product is at its best when the content is a collaboration between the builders and consumers of that product. As such, this documentation is both public, and open sourced. That means you can clone this repository, read the docs off line, or even load the entire thing to an Apple Newton, if that's your thing.

diff --git a/basic-usage/capture-https-traffic.md b/basic-usage/capture-https-traffic.md index a7d83ec..48e6795 100644 --- a/basic-usage/capture-https-traffic.md +++ b/basic-usage/capture-https-traffic.md @@ -8,40 +8,44 @@ position: 3 # Capture HTTP/S Traffic with FiddlerCore -This article expains how to capture HTTP/S traffic with FiddlerCore +This article explains how to capture HTTP/S traffic with FiddlerCore Once FiddlerCore is [configured]({%slug configuration %}), it starts to listen for a traffic on the background. When it captures any session, it notifies you by raising the following events: ->It is important to understand that FiddlerCore calls event handlers on session-handling background threads. +>The following event handlers are invoked on session-handling **background threads**. +> +>If you need to need to update a UI thread (e.g. in WPF or Windows Forms application), you may need to delegate the update logic back to the UI thread, for example by using [Dispatcher.BeginInvoke](https://docs.microsoft.com/en-us/dotnet/api/system.windows.threading.dispatcher.begininvoke) (WPF) or [Control.Invoke](https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.control.invoke) (Windows Forms). +> +>Also, if you use collections that are not thread-safe, like [`List`](https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.list-1), you may need to employ additional synchronization mechanisms. ## FiddlerApplication.BeforeRequest You should use this event to act when client request is received. For example, you can modify the session flags to use specific ssl protocols. - - Fiddler.FiddlerApplication.BeforeRequest += session => +```c# + FiddlerApplication.BeforeRequest += session => { session["x-OverrideSslProtocols"] = "ssl3;tls1.0;tls1.1;tls1.2"; }; - +``` ## FiddlerApplication.BeforeResponse -You should use this event to act when a server responce is received. For example, you can decode the body. - - Fiddler.FiddlerApplication.BeforeResponse += session => +You should use this event to act when a server response is received. For example, you can decode the body. +```c# + FiddlerApplication.BeforeResponse += session => { session.utilDecodeResponse(); }; - +``` ## FiddlerApplication.AfterSessionComplete You should use this event to act when a session is completed. For example, notify the user. - +```c# FiddlerApplication.AfterSessionComplete += session => { Console.WriteLine($"Finished session: {session.fullUrl}"); } - ->tip These are only the most commonly used handlers. For the full list of events check [this article](/api/fiddler.fiddlerapplication) +``` +>tip These are only the most commonly used handlers. For the full list of events check [FiddlerApplication's API reference](/api/fiddler.fiddlerapplication). ## Next Steps diff --git a/basic-usage/configuration.md b/basic-usage/configuration.md index 92bb34b..36080c5 100644 --- a/basic-usage/configuration.md +++ b/basic-usage/configuration.md @@ -86,6 +86,14 @@ FiddlerApplication.Prefs.SetStringPref("fiddler.proxy.pacfile.text", "return 'PR - `DecryptSSL()`: Enables decryption of HTTPS traffic. You should have a CertificateProvider loaded with trusted certificate. For more details see [Use Custom Root Certificate]({%slug use-custom-root-certificate %}) article. - `OptimizeThreadPool()`: Optimizes the thread pool to better handle multiple simultaneous threads. This is often convenient, as each `Session` is handled in a different thread. Under the hood, this methods uses [`ThreadPool.SetMinThreads`](https://docs.microsoft.com/en-us/dotnet/api/system.threading.threadpool.setminthreads) with a value larger that the default one. +## Handling events +`FiddlerApplication` exposes numerous events, described in more details in the [Capture HTTP/S Traffic] article (%slug capture-https-traffic) article. + +## Shutdown +`FidlerCore can be shut down using the following method of `FiddlerApplication` +- `Shutdown()`: Shuts down FiddlerCore, and reverts the proxy settings to the original ones, in case they were modified on startup. +>noteIf there is traffic in progress when calling `FiddlerApplication.Shutdown()`, some of the background threads handling the sessions may throw `ObjectDisposedException` or `NullReferenceException`. + ## Next Steps - [Register as System Proxy]({%slug register-as-system-proxy %}) diff --git a/basic-usage/import-export-sessions.md b/basic-usage/import-export-sessions.md index 8aba976..ef714ca 100644 --- a/basic-usage/import-export-sessions.md +++ b/basic-usage/import-export-sessions.md @@ -8,12 +8,12 @@ position: 4 # Import and Export Sessions with FiddlerCore -This article expains how to import and export sessions with FiddlerCore. +This article explains how to import and export sessions with FiddlerCore. ## Import Sessions You can import sessions with FiddlerCore by using the following code: - +```c# Session[] loaded = Utilities.ReadSessionArchive(sazFilename, false, "", (file, part) => { Console.WriteLine($"Enter the password for { part } (or just hit Enter to cancel):"); @@ -22,15 +22,18 @@ You can import sessions with FiddlerCore by using the following code: return sResult; }); +``` ## Export Sessions You can export sessions with FiddlerCore by using the following code: - +```c# bool success = Utilities.WriteSessionArchive(filename, sessions.ToArray(), password, false); +``` ## Custom SAZ Provider -There are cases that you may want to use custom provider to save FiddlerCore sessions. You do this by setting the following property: - +There are cases when you may want to use custom provider to save FiddlerCore sessions. You do this by setting the following property: +```c# FiddlerApplication.oSAZProvider = new CustomSazProvider(); +``` diff --git a/basic-usage/register-as-system-proxy.md b/basic-usage/register-as-system-proxy.md index cb9c306..07b8b34 100644 --- a/basic-usage/register-as-system-proxy.md +++ b/basic-usage/register-as-system-proxy.md @@ -16,16 +16,46 @@ The simplest way to register FiddlerCore as a system proxy is by passing `Fiddle ```c# FiddlerCoreStartupSettings startupSettings = new FiddlerCoreStartupSettingsBuilder() - .ListenOnPort(fiddlerCoreListenPort) .RegisterAsSystemProxy() .Build(); FiddlerApplication.Startup(startupSettings); ``` +There are more basic methods affecting the system proxy settings in the FiddlerCoreStartupSettings. You can read more in [Configuration/Proxy settings]({%slug configuration %}#system-proxy-settings) article. + ## Advanced approach +Instead of using the basic configuration methods, you can manually modify the proxy settings. The logic for modifying the system connections' proxy settings is separated in the Telerik.NetworkConnections assembly. +It contains the following key members: +- `INetworkConnectionsDetector`: Base interface representing network connection detector. It contains a single `Detect()` method, which should return a set of `NetworkConnection` instances of a particular type. +- `NetworkConnection`: Base abstract class which allows manipulation and monitoring of proxy settings for a specific network connection. The most important members are: + - `GetCurrentProxySettings()`: Returns the current `ProxySettings` for the connection. + - `SetProxySettings(ProxySettings)`: Sets specified proxy settings for the connection. + - `ProxySettingsChanged`: Event raised when proxy settings for the connection are changed. + +To manually manipulate network connections' proxy settings, you can use any of the built-in detectors, obtain an instance of a NetworkConnection class, and invoke it's `SetProxySettings` method, for example: +```c# +// Detect the network connections: +var networkConnections = new WinINetNetworkConnectionsDetector().Detect(); + +// Create appropriate proxy settings (in this case bypassing particular hosts): +var proxySettings = new ProxySettings(true, "https://www.telerik.com"); + +// Modify some of the network connections: +networkConnections.First().SetProxySettings(proxySettings); + +// Start: +FiddlerApplication.Startup(new FiddlerCoreStartupSettingsBuilder().Build()); +``` + +The following default implementations for `INetworkConnectionsDetector` are provided: +- `WinINetNetworkConnectionsDetector`: detector for Windows-specific Windows Internet (WinINET) networking component network connection. +- `RasNetworkConnectionsDetector`: detector for Windows-specific RAS network connections. +- `MacNetworkConnectionsDetector`: Detector for Mac-specific network connections. +- `LinuxNetworkConnectionsDetector`: Detector for Linux-specific network connections. +>noteThe built-in connection detectors are OS-specific and will throw exception if invoked on a not-supported platforms. ## Next Steps diff --git a/basic-usage/use-custom-root-certificate.md b/basic-usage/use-custom-root-certificate.md index 5407da8..d62580c 100644 --- a/basic-usage/use-custom-root-certificate.md +++ b/basic-usage/use-custom-root-certificate.md @@ -16,14 +16,15 @@ FiddlerCore will create new certificate every time the application runs. This ex ## Set the Default Certificate Provider The following code explains how to set the default certificate provider for FiddlerCore: - +```c# BCCertMaker.BCCertMaker certProvider = new BCCertMaker.BCCertMaker(); CertMaker.oCertProvider = certProvider; +``` ## Create Root Certificate The following code explains how to create your own root certificate. - +```c# string rootCertificatePath = @"Path\To\Your\Root\Certificate\RootCertificate.p12"; string rootCertificatePassword = "S0m3T0pS3cr3tP4ssw0rd"; if (!File.Exists(rootCertificatePath)) @@ -31,26 +32,29 @@ The following code explains how to create your own root certificate. certProvider.CreateRootCertificate(); certProvider.WriteRootCertificateAndPrivateKeyToPkcs12File(rootCertificatePath, rootCertificatePassword); } +``` ## Read Root Certificate from File The following code explains how to create your own root certificate. - +```c# string rootCertificatePath = @"Path\To\Your\Root\Certificate\RootCertificate.p12"; string rootCertificatePassword = "S0m3T0pS3cr3tP4ssw0rd"; if (File.Exists(rootCertificatePath)) { certProvider.ReadRootCertificateAndPrivateKeyFromPkcs12File(rootCertificatePath, rootCertificatePassword); } +``` ## Trust Root Certificate The following code explains how to trust your root certificate. - +```c# if (!CertMaker.rootCertIsTrusted()) { CertMaker.trustRootCert(); } +``` ## Next Steps diff --git a/getting-started/download-product-files.md b/getting-started/download-product-files.md index ace6cf4..2fa8592 100644 --- a/getting-started/download-product-files.md +++ b/getting-started/download-product-files.md @@ -21,7 +21,7 @@ In order to download these you need to take the following steps: ![](images/download_product_files_1.png) -**3. Select __Telerik UI for Xamarin__ product title:** +**3. Select __FiddlerCore__ product title:** ![](images/download_product_files_2.png) @@ -41,4 +41,4 @@ Below you could find a list of the available files: ## Next Steps -- [FiddlerCore Configuration]({%slug configuration%}) \ No newline at end of file +- [FiddlerCore Configuration]({%slug configuration%}) diff --git a/getting-started/system-requirements.md b/getting-started/system-requirements.md index 72c984e..b18d23f 100644 --- a/getting-started/system-requirements.md +++ b/getting-started/system-requirements.md @@ -40,4 +40,4 @@ In order to develop applications with **Telerik FiddlerCore** you need to have t ## Next Steps * [Download Product Files]({%slug download-product-files%}) -* [Use Telerik NuGet Server]({%slug telerik-nuget-server%}) \ No newline at end of file +* [Use Telerik NuGet Server]({%slug telerik-nuget-server%})