Skip to content

Commit f152f66

Browse files
AntarisAntaris
committed
feat: Docs
1 parent 0c500f0 commit f152f66

32 files changed

+16052
-0
lines changed

‎docs/.gitignore

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎docs/babel.config.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎docs/blog/2019-05-28-first-blog-post.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
slug: first-blog-post
3+
title: First Blog Post
4+
authors:
5+
name: Gao Wei
6+
title: Docusaurus Core Team
7+
url: https://github.com/wgao19
8+
image_url: https://github.com/wgao19.png
9+
tags: [hola, docusaurus]
10+
---
11+
12+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

‎docs/blog/2019-05-29-long-blog-post.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
slug: long-blog-post
3+
title: Long Blog Post
4+
authors: endi
5+
tags: [hello, docusaurus]
6+
---
7+
8+
This is the summary of a very long blog post,
9+
10+
Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
11+
12+
<!--truncate-->
13+
14+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
15+
16+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
17+
18+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
19+
20+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
21+
22+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
23+
24+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
25+
26+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
27+
28+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
29+
30+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
31+
32+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
33+
34+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
35+
36+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
37+
38+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
39+
40+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
41+
42+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
43+
44+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

‎docs/blog/2021-08-01-mdx-blog-post.mdx

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
slug: mdx-blog-post
3+
title: MDX Blog Post
4+
authors: [slorber]
5+
tags: [docusaurus]
6+
---
7+
8+
Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
9+
10+
:::tip
11+
12+
Use the power of React to create interactive blog posts.
13+
14+
```js
15+
<button onClick={() => alert('button clicked!')}>Click me!</button>
16+
```
17+
18+
<button onClick={() => alert('button clicked!')}>Click me!</button>
19+
20+
:::

‎docs/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg

93.9 KB
Loading

‎docs/blog/2021-08-26-welcome/index.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
slug: welcome
3+
title: Welcome
4+
authors: [slorber, yangshun]
5+
tags: [facebook, hello, docusaurus]
6+
---
7+
8+
[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
9+
10+
Simply add Markdown files (or folders) to the `blog` directory.
11+
12+
Regular blog authors can be added to `authors.yml`.
13+
14+
The blog post date can be extracted from filenames, such as:
15+
16+
- `2019-05-30-welcome.md`
17+
- `2019-05-30-welcome/index.md`
18+
19+
A blog post folder can be convenient to co-locate blog post images:
20+
21+
![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
22+
23+
The blog supports tags as well!
24+
25+
**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.

‎docs/blog/authors.yml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
endi:
2+
name: Endilie Yacop Sucipto
3+
title: Maintainer of Docusaurus
4+
url: https://github.com/endiliey
5+
image_url: https://github.com/endiliey.png
6+
7+
yangshun:
8+
name: Yangshun Tay
9+
title: Front End Engineer @ Facebook
10+
url: https://github.com/yangshun
11+
image_url: https://github.com/yangshun.png
12+
13+
slorber:
14+
name: Sébastien Lorber
15+
title: Docusaurus maintainer
16+
url: https://sebastienlorber.com
17+
image_url: https://github.com/slorber.png

‎docs/docs/client-usage.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
sidebar_position: 3
3+
tags: [HTTP Client, API Client, Dependency Injection]
4+
---
5+
6+
# API Client Usage
7+
8+
There are a number of ways to create an API client for accessing the WebTrends API. The approach you take will depend on how your app works.
9+
10+
:::tip[Examples]
11+
12+
Examples on this page are using the C# default constructors feature for brevity. The approaches listed here will work with typical constructors.
13+
14+
:::
15+
16+
## Using Dependency Injection (DI)
17+
18+
You can use DI to inject a client into your app code.
19+
20+
### Using the default client
21+
22+
The default client is pre-configured to use the configured `WebTrendsSettings`. The client will be disposed when the owning scope is disposed.
23+
24+
```csharp
25+
public class MyService(IWebTrendsApiClient client)
26+
{
27+
public async Task DoSomething()
28+
{
29+
// Do something with client.
30+
}
31+
}
32+
```
33+
34+
### Using the API client factory
35+
36+
It is possible to inject the API client factory and settings instead. You need to manage the lifetime of the client itself.
37+
38+
```csharp
39+
public class MyService(IWebTrendsApiClientFactory clientFactory, WebTrendsSettings settings)
40+
{
41+
public async Task DoSomething()
42+
{
43+
using var client = clientFactory.CreateApiClient(settings);
44+
45+
// Do something with client.
46+
}
47+
}
48+
```
49+
50+
If you are not using the pre-configured `WebTrendsSettings`, you can provided your own:
51+
52+
```csharp
53+
public class MyService(IWebTrendsApiClientFactory clientFactory)
54+
{
55+
public async Task DoSomething()
56+
{
57+
var settings = new WebTrendsSettings();
58+
using var client = clientFactory.CreateApiClient(settings);
59+
60+
// Do something with client.
61+
}
62+
}
63+
```
64+
65+
### Manually creating a client
66+
67+
You can manually create a client yourself, but you are responsible for managing its lifetime. The following are some examples.
68+
69+
#### Creating an API client manually
70+
71+
```csharp
72+
var httpClient = new HttpClient();
73+
var settings = new WebTrendsSettings();
74+
75+
var apiClient = new WebTrendsApiClient(httpClient, settings);
76+
```
77+
78+
#### Creating an API client factory manually
79+
80+
```csharp
81+
var httpClientFactory = new WebTrendsHttpClientFactory();
82+
var apiClientFactory = new WebTrendsApiClientFactory(httpClientFactory);
83+
var settings = new WebTrendsSettings();
84+
85+
var apiClient = apiClientFactory.CreateApiClient(settings);
86+
```
87+
88+
### Managing the HTTP Client
89+
90+
If you need to control how the `HttpClient` is created, you can implement your own implementaton of `IWebTrendsHttpClientFactory`:
91+
92+
```csharp
93+
public class MyWebTrendsHttpClientFactory : IWebTrendsHttpClientFactory
94+
{
95+
public HttpClient CreateClient(string name)
96+
{
97+
return new HttpClient();
98+
}
99+
}
100+
```
101+
102+
If you are using the standard approach to dependency injection, you can register your own implementation, which will be used instead of the default implementation:
103+
104+
```csharp
105+
services.AddWebTrends();
106+
services.AddScoped<IWebTrendsHttpClientFactory, MyWebTrendsHttpClientFactory>();
107+
```

‎docs/docs/configure.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
sidebar_position: 2
3+
title: Configure
4+
description: Details how to configure the WebTrendsSDK library within your project
5+
tags: [Getting started, Configuration]
6+
---
7+
8+
# Configure
9+
10+
The WebTrendsSDK targets .NET Standard 2.0 (`netstandard2.0`) which means you can install the SDK on any project that supports .NET Standard 2.0. You can view the [supported frameworks and platforms](https://www.nuget.org/packages/WebTrendsSDK#supportedframeworks-body-tab) on NuGet.org.
11+
12+
## .NET Core and .NET 5+
13+
14+
Apps written for the newer .NET platform can be configured to use the WebTrendsSDK through app configuration and service registration.
15+
16+
### Configuring WebTrends settings
17+
To configure the WebTrendsSDK, add the following to your `appsettings.json` file:
18+
19+
```json
20+
{
21+
"WebTrends": {
22+
"AccountId": "{account_id}",
23+
"KeyToken": "{token}",
24+
"WebsiteUrl": "{website_url}
25+
}
26+
}
27+
```
28+
29+
The app configuration is mapped to the `WebTrendsSettings` type, which supports the following properties:
30+
31+
| Property | Type | Default Value | Notes |
32+
| --- | --- | --- | --- |
33+
| `AccountId` | `string` | `null` | Your account ID |
34+
| `KeyToken` | `string` | `null` | Your authentication token |
35+
| `OtsBaseUrl` | `string` | https://ots.webtrends-optimize.com | The base URL for the WebTrends OTS REST API |
36+
| `CaptureRequestContent` | `bool` | `false` | If enabled, each request will capture the request content |
37+
| `CaptureResponseContent` | `bool` | `false` | If enabled, each request will capture the response content |
38+
39+
### Service registration
40+
To add WebTrendsSDK services to your Dependency Injection container, you need to add a call to `AddWebTrends()` to your `IServiceCollection`. There are a few _flavours_ of a .NET app, so you'll need to decide which one you are using
41+
42+
#### Using `WebApplication.CreateBuilder()`
43+
This is the typical approach to modern ASP.NET Core apps, typically using Minimal APIs.
44+
45+
```csharp
46+
var builder = WebApplication.CreateBuilder(args);
47+
48+
builder.Services.AddWebTrends();
49+
```
50+
51+
#### Using a Startup class
52+
This is an approach used by ASP.NET Core web apps.
53+
54+
```csharp
55+
public class Startup
56+
{
57+
public void ConfigureServices(IServiceCollection services)
58+
{
59+
services.AddWebTrends();
60+
}
61+
}
62+
```
63+
64+
#### Using `HostBuilder`
65+
The `HostBuilder` approach targets non-ASP.NET Core scenarios, such as Windows services, or Function apps (Azure Functions, AWS Lambda, etc.) that require host lifetime management.
66+
67+
```csharp
68+
var builder = new HostBuilder()
69+
.ConfigureServices(services => {
70+
servies.AddWebTrends();
71+
});
72+
```
73+
74+
:::warning[Note on Lifetime]
75+
76+
The `AddWebTrends()` extension method registers a per-scope lifetime for the default API client. This is typical for ASP.NET Core apps where the lifetime scope is per-request. For non-ASP.NET Core hosts, you may need to manage the lifetime through a lifetime scope, otherwise you may up with a singleton instance of the client.
77+
78+
:::
79+
80+
## .NET Framework
81+
82+
### Vanilla .NET Framework
83+
84+
If you are targeting .NET Framework but will be managing the lifetime of the SDK services yourself, you can easily create an instance of a client and settings. See [Client Usage](/docs/client-usage) for more information.
85+
86+
### Integration through an Inversion of Control (IoC) container
87+
88+
If you are targeting .NET Framework, you may or may not be using a IoC container, such as Autofac, or StructureMap, etc. It is possible to wire up the WebTrendsSDK using the same strategy as the default for ASP.NET Core, however as there are numerous IOC containers available, we haven't documented them here. Below is an outline of the recommended service lifetime for the services provided by the SDK:
89+
90+
| Service | Implementation | Recommended Lifetime | Notes |
91+
| --- | --- | --- | --- |
92+
| `WebTrendsSettings` | `WebTrendsSettings` | `Singleton` | Pre-configure this instance. |
93+
| `IWebTrendsHttpClientFactory` | `WebTrendsHttpClientFactory` | `Scoped` | This is for customising a `HttpClient` instance. |
94+
| `IIsuuApiClientFactory` | `WebTrendsApiClientFactory` | `Scoped` | |
95+
| `IIsuuApiClient` | `WebTrendsApiClient` | `Scoped` | This is the default instance when injected directly. |

0 commit comments

Comments
 (0)