Skip to content

Commit 6774159

Browse files
skttlskttl
committed
Updates docs
1 parent 0b158b1 commit 6774159

File tree

11 files changed

+168
-94
lines changed

11 files changed

+168
-94
lines changed

‎README.md‎

Lines changed: 11 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,31 @@
11
# ImageSharpCommunity.Providers.Remote
22

3+
[![Downloads](https://img.shields.io/nuget/dt/ImageSharpCommunity.Providers.Remote?color=cc9900)](https://www.nuget.org/packages/ImageSharpCommunity.Providers.Remote/)
4+
[![NuGet](https://img.shields.io/nuget/vpre/ImageSharpCommunity.Providers.Remote?color=0273B3)](https://www.nuget.org/packages/ImageSharpCommunity.Providers.Remote)
5+
[![GitHub license](https://img.shields.io/github/license/skttl/ImageSharp.Community.Providers.Remote?color=8AB803)](https://github.com/skttl/ImageSharp.Community.Providers.Remote/blob/main/LICENSE)
6+
37
ImageSharpCommunity.Providers.Remote is a library that provides remote image loading functionality for the ImageSharp.Web library. It allows you to load images from remote URLs and integrate them seamlessly into your ImageSharp-based applications.
48

9+
[A wrapper package for Umbraco, simplyfying the setup is also available!](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/umbraco-marketplace-readme.md)
10+
511
## Installation
612

713
You can install the library via NuGet.
814

9-
# [Package Manager](#tab/tabid-1)
10-
11-
```bash
12-
PM > Install-Package ImageSharpCommunity.Providers.Remote -Version VERSION_NUMBER
13-
```
14-
15-
# [.NET CLI](#tab/tabid-2)
16-
1715
```bash
1816
dotnet add package ImageSharpCommunity.Providers.Remote --version VERSION_NUMBER
1917
```
2018

21-
# [PackageReference](#tab/tabid-3)
22-
23-
```xml
24-
<PackageReference Include="ImageSharpCommunity.Providers.Remote" Version="VERSION_NUMBER" />
25-
```
26-
27-
# [Paket CLI](#tab/tabid-4)
28-
29-
```bash
30-
paket add ImageSharpCommunity.Providers.Remote --version VERSION_NUMBER
31-
```
32-
33-
## Usage
34-
35-
To use the `ImageSharpCommunity.Providers.Remote` library, register the remote image provider in your application's services configuration. This can typically be done in the ConfigureServices method of your Startup class:
36-
37-
```csharp
38-
public void ConfigureServices(IServiceCollection services)
39-
{
40-
// Other services configuration...
41-
42-
services.AddImageSharp()
43-
.Configure<RemoteImageProviderOptions>(options =>
44-
{
45-
options.Settings
46-
.Add(new("/remote")
47-
{
48-
AllowedDomains = new List<string>() { "*" }
49-
});
50-
})
51-
.InsertProvider<RemoteImageProvider>(0);
52-
}
53-
```
54-
55-
If you are using the default `WebRootProvider`, you need to make sure the `RemoteImageProvider` is inserted before that. Hence why `InsertProvider` is used instead of `AddProvider` in the above example.
56-
57-
By default, no domains is allowed, so you have to configure your desired `RemoteImageProviderOptions` in order to use this provider.
58-
59-
## Configuration Options
60-
61-
The `RemoteImageProviderOptions` class provides the following configuration options:
62-
63-
- `Settings`: A list of the different allowed sources for images.
64-
65-
Each setting (`RemoteImageProviderSetting`) provides the following configuration options:
66-
67-
- `Prefix`: Specified in the constructor, and defines the local path to prefix all remote image requests with. For example, setting this to `/remote` allows requests like `/remote/https://test.com/test.png` to pass through this provider.
68-
69-
- `RemoteUrlPrefix` (optional): Prefixes the URL on the server. For example, setting this to `https://test.com/` allows requests like `/remote/test.png` to download `https://test.com/test.png`. Note: You still need to allow the specific domain in the `AllowedDomains` setting.
70-
71-
- `MaxBytes`: Specifies the maximum allowable download size in bytes. By default, it is set to `4194304` bytes (4 MB).
72-
73-
- `Timeout`: Sets the timeout for a request in milliseconds. By default, it is set to `3000` milliseconds (3 seconds).
74-
75-
- `UserAgent`: Sets a user agent value for the request. This can be useful for interacting with social networks. By default, it is set to `"ImageSharpRemoteProvider/0.1"`.
76-
77-
- `HttpClientName`: Sets the name of the HttpClient to use when downloading images. By default, it is set to `"ImageSharpRemoteProvider/HttpClient"`.
78-
79-
- `AllowedDomains`: Specifies a list of allowable domains to process images from. Images from domains not listed here will be blocked. This is an empty list by default. You can add `*` to allow all domains.
80-
81-
- `AdditionalOptions`: Allows specifying additional `RemoteImageProviderOptions` instances. This can be useful when you have multiple configurations with different prefixes or other settings.
82-
83-
Please note that these options provide customization and control over how remote images are loaded and processed. You can adjust these options according to your specific requirements.
84-
85-
Don't forget to configure these options in your application's services configuration as shown in the Usage section of this README.
19+
## Documentation
8620

87-
Please refer to the documentation or the XML comments in the code for more information about each option and its usage.
21+
- [Setup](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup.md)
22+
- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
23+
- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/usage.md)
8824

8925
## Contributing
9026

9127
Contributions to the `ImageSharpCommunity.Providers.Remote` library are welcome! If you encounter any issues or have suggestions for improvements, please feel free to create a new issue or submit a pull request.
9228

9329
## License
9430

95-
The `ImageSharpCommunity.Providers.Remote` library is licensed under the [MIT License](https://opensource.org/licenses/MIT). Please see the [LICENSE](LICENSE) file for more details.
31+
The `ImageSharpCommunity.Providers.Remote` library is licensed under the [MIT License](https://opensource.org/licenses/MIT). Please see the [LICENSE](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/LICENSE) file for more details.

‎docs/README_nuget.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/README_nuget_Umbraco.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/configuration.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Configuration Options
2+
3+
The `RemoteImageProviderOptions` class provides the following configuration options:
4+
5+
- `Settings`: A list of the different allowed sources for images.
6+
7+
Each setting (`RemoteImageProviderSetting`) provides the following configuration options:
8+
9+
- `Prefix`: Specified in the constructor, and defines the local path to prefix all remote image requests with. For example, setting this to `/remote` allows requests like `/remote/https://test.com/test.png` to pass through this provider.
10+
11+
- `RemoteUrlPrefix` (optional): Prefixes the URL on the server. For example, setting this to `https://test.com/` allows requests like `/remote/test.png` to download `https://test.com/test.png`. Note: You still need to allow the specific domain in the `AllowedDomains` setting.
12+
13+
- `MaxBytes`: Specifies the maximum allowable download size in bytes. By default, it is set to `10485760` bytes (10 MB).
14+
15+
- `Timeout`: Sets the timeout for a request in milliseconds. By default, it is set to `180000` milliseconds (180 seconds - 3 minutes).
16+
17+
- `UserAgent`: Sets a user agent value for the request. This can be useful for interacting with social networks. By default, it is set to `"ImageSharpRemoteProvider/[current version]"`.
18+
19+
- `HttpClientName`: Sets the name of the HttpClient to use when downloading images. By default, it is set to `"ImageSharpRemoteProvider/HttpClient"`.
20+
21+
- `AllowedDomains`: Specifies a list of allowable domains to process images from. Images from domains not listed here will be blocked. This is an empty list by default. You can add `*` to allow all domains. This can be used instead of, or in combination with `AllowedDomainsRegex`.
22+
23+
- `AllowedDomainsRegex`: Specifies a list of regex patterns, matching allowable domains to process images from. Images from domains not matching any of the regexes will be blocked. This is an empty list by default. This can be used instead of, or in combination with `AllowedDomains`.
24+
25+
- `AllowAllDomains`: Boolean value. If set to true, all domains is allowed to process.
26+
27+
- `AdditionalOptions`: Allows specifying additional `RemoteImageProviderOptions` instances. This can be useful when you have multiple configurations with different prefixes or other settings.
28+
29+
Please note that these options provide customization and control over how remote images are loaded and processed. You can adjust these options according to your specific requirements.
30+
31+
Don't forget to configure these options in your application's services configuration as shown in the Usage section of this README.
32+
33+
Please refer to the documentation or the XML comments in the code for more information about each option and its usage.
34+
35+
- [Setup](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup.md) ([Umbraco](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup-umbraco.md))
36+
- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/usage.md)

‎docs/setup-umbraco.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Setup
2+
3+
`Umbraco.Community.ImageSharpRemoteImages` is registered automatically when Umbraco starts, you just need to configure it.
4+
5+
You can configure using appsettings.json, and a schema file is provided for easier setup.
6+
7+
A configuration can look like this:
8+
9+
```json
10+
{
11+
"Umbraco": {
12+
"Community": {
13+
"ImageSharpRemoteImages": {
14+
"Settings": [
15+
{
16+
"Prefix": "/ourumb",
17+
"RemoteUrlPrefix": "https://our.umbraco.com",
18+
"AllowedDomains": [ "our.umbraco.com" ]
19+
},
20+
{
21+
"Prefix": "/remote",
22+
"AllowedDomains": ["*"]
23+
}
24+
]
25+
}
26+
}
27+
}
28+
```
29+
30+
By default, no domains is allowed, so you have to configure your desired `RemoteImageProviderOptions` in order to use this provider.
31+
32+
- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
33+
- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/usage.md)

‎docs/setup.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Setup
2+
3+
To use the `ImageSharpCommunity.Providers.Remote` library, register the remote image provider in your application's services configuration. This can typically be done in the ConfigureServices method of your Startup class:
4+
5+
```csharp
6+
public void ConfigureServices(IServiceCollection services)
7+
{
8+
// Other services configuration...
9+
10+
services.AddImageSharp()
11+
.Configure<RemoteImageProviderOptions>(options =>
12+
{
13+
options.Settings
14+
.Add(new("/remote")
15+
{
16+
AllowedDomains = new List<string>() { "*" }
17+
});
18+
})
19+
.InsertProvider<RemoteImageProvider>(0);
20+
}
21+
```
22+
23+
If you are using the default `WebRootProvider`, you need to make sure the `RemoteImageProvider` is inserted before that. Hence why `InsertProvider` is used instead of `AddProvider` in the above example.
24+
25+
By default, no domains is allowed, so you have to configure your desired `RemoteImageProviderOptions` in order to use this provider.
26+
27+
- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
28+
- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)

‎docs/usage.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Usage
2+
3+
Given the [example config](setup.md) ([for Umbraco here](setup-umbraco.md)), you can now request remote images using the path `/remote/https://test.com/path/to/img.jpg`.
4+
5+
If using the RemoteUrlPrefix option, you can omit everything stated in the config. Eg. having set RemoteUrlPrefix to `https://test.com`, you can request images at `/remote/path/to/img.jpg`, which would then resolve to `https://test.com/path/to/img.jpg`.
6+
7+
## Resolving "local" URL by remote URL
8+
9+
If you don't like to hardcode URLs to images like the above, there is an extension method in `ImageSharpCommunity.Providers.Remote.Helpers` you can use to resolve the local URL.
10+
11+
You need to inject the RemoteImageProviderOptions in first, and then you call it like `uri.GetRemoteImageProviderUrl(options)`
12+
13+
Heres an example in a Razor view:
14+
15+
```cshtml
16+
@using ImageSharpCommunity.Providers.Remote;
17+
@using ImageSharpCommunity.Providers.Remote.Configuration;
18+
@inject IOptions<RemoteImageProviderOptions> RemoteImageProviderOptions;
19+
@{
20+
var uri = new Uri("https://test.com/path/to/image.jpg");
21+
var localUrl = uri.GetRemoteImageProviderUrl(RemoteImageProviderOptions.Value); // "/remote/https://test.com/path/to/img.jpg"
22+
}
23+
```
24+
25+
- [Setup](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup.md) ([Umbraco](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup-umbraco.md))
26+
- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)

‎src/ImageSharpCommunity.Providers.Remote/Configuration/RemoteImageProviderSetting.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ public RemoteImageProviderSetting(string prefix)
3535
/// <summary>
3636
/// Sets a useragent value for the request. Useful for social networks. See http://www.useragentstring.com/ for available values.
3737
/// </summary>
38-
public string UserAgent { get; set; } = "ImageSharpRemoteProvider/0.1";
38+
public string UserAgent { get; set; } = "ImageSharpRemoteProvider/" + typeof(RemoteImageProviderSetting).Assembly.GetName().Version;
3939

4040
/// <summary>
4141
/// Sets the name of the HttpClient to use when downloading images.

‎src/ImageSharpCommunity.Providers.Remote/ImageSharpCommunity.Providers.Remote.csproj‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
<PackageId>ImageSharpCommunity.Providers.Remote</PackageId>
1515
<PackageLicenseExpression>MIT</PackageLicenseExpression>
1616
<PackageProjectUrl>https://github.com/skttl/ImageSharpCommunity.Providers.Remote</PackageProjectUrl>
17-
<PackageReadmeFile>README_nuget.md</PackageReadmeFile>
17+
<PackageReadmeFile>README.md</PackageReadmeFile>
1818
<PackageTags>image</PackageTags>
1919
<Product>ImageSharpCommunity.Providers.Remote</Product>
2020
<RepositoryType>git</RepositoryType>
@@ -30,7 +30,7 @@
3030
</ItemGroup>
3131

3232
<ItemGroup>
33-
<None Include="..\..\docs\README_nuget.md">
33+
<None Include="..\..\README.md">
3434
<Pack>True</Pack>
3535
<PackagePath>\</PackagePath>
3636
</None>

‎src/Umbraco.Community.ImageSharpRemoteImages/Umbraco.Community.ImageSharpRemoteImages.csproj‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
<PackageId>Umbraco.Community.ImageSharpRemoteImages</PackageId>
1515
<PackageLicenseExpression>MIT</PackageLicenseExpression>
1616
<PackageProjectUrl>https://github.com/skttl/ImageSharp.Community.Providers.Remote</PackageProjectUrl>
17-
<PackageReadmeFile>README_nuget.md</PackageReadmeFile>
17+
<PackageReadmeFile>README.md</PackageReadmeFile>
1818
<PackageTags>image umbraco umbraco-marketplace</PackageTags>
1919
<Product>Umbraco.Community.ImageSharpRemoteImages</Product>
2020
<RepositoryType>git</RepositoryType>
@@ -30,7 +30,7 @@
3030
<Content Include="buildTransitive\**" PackagePath="buildTransitive" />
3131
</ItemGroup>
3232
<ItemGroup>
33-
<None Include="..\..\docs\README_nuget.md" Link="README_nuget.md">
33+
<None Include="..\..\umbraco-marketplace-readme.md" Link="README.md">
3434
<PackagePath>\</PackagePath>
3535
<Pack>True</Pack>
3636
</None>

0 commit comments

Comments
 (0)