Dangl.Icons
Configuration
In development, ensure that the AppFilesRootPath
setting is configured, ideally via user secrets.
Integrated Server Configuration
If you're using the Dangl.Icons.Server
NuGet package to bundle the server side features directly in your backend, please see
the following configuration example. Additionally, make sure that you configure your own
Dangl.AspNetCore.FileHandling.IFileManager
service. By default, the identicons are saved in a container named identicons
. This
constant is available in Dangl.Icons.Server.IconAppDefaults.IDENTICONS_CONTAINER_NAME
.
// Adds the required services for dependency injection
services.AddDanglIconsServices();
// Adds the Dangl.Icons controllers to your app
services.AddMvc().AddDanglIconsControllers();
// If you want to be able to upload icons, you must configure a Policy. It's default name
// is 'IconManagerPolicy' (see Dangl.Icons.Server.IconAppDefaults.ICON_MANAGER_POLICY_NAME)
// For example, this could be a policy configuration in your app:
services.AddAuthorization(authConfig =>
{
authConfig.AddPolicy(IconAppDefaults.ICON_MANAGER_POLICY_NAME,
policyBuilder => policyBuilder
.AddRequirements(new IconManagerRequirement(iconAppConfiguration.ApiKeys)));
});
Excluding Dangl.Icons.Server
By default, ASP.NET Core MVC will add controllers discovered in all loaded assemblies at startup. If the Dangl.Icons.Server package is included in your app but you do not want to automatically load the controllers, ensure the following service call:
services.AddMvc().EnsureDanglIconsControllersAreExcluded();
Authorization
Retrieving icons is not access restricted. Icons are saved by a Guid and are accessible
via /api/identicons/{iconId}.png
. Consuming apps may use anything as identifier. For example,
apps can simply generate a Guid and assign this for an user to be used as identicon. This may be
changed at any time.
Some features require authentication and authorization, for example icon uploads. This app uses Jwt Bearer authentication. Valid authorities and required scopes are configured in the app config, as well as the name of the claim that is required to access this functionality.
Config Value | Type | Description |
---|---|---|
IconManagerClaimName |
string |
The name of the claim that is evaluated for access |
JwtBearerRequiredScope |
string |
The scope required in the Jwt tokens |
JwtBearerAuthorities |
List<string> |
The list of valid authorities that may issue Jwt tokens |
The IconManagerClaimName
may be either set to true
or specify an ISO 8601 timestamp to indicate
until when it is valid.
Authorization via Api Keys
Additionally, it is possible to configure Api Keys to be used as authorization mechanism. To do this,
simply supply an array of valid api keys in the ApiKeys
configuration property.
The keys must be sent with each request in a http header X-DANGL-ICONS-API-KEY
, which is also available
as a constant value in IconManagerRequirementHandler.API_KEY_HEADER_NAME
.
PNG Extension
All requests for identicons must have the png extension: /api/identicons/{iconId}.png
This is to allow caching of the icons in some CDNs that only cache specific file extensions. Internally, uploaded icons are always converted to png.
Identicon Generation Options
The /api/identicons/{iconId}.png
endpoint has the following parameters:
size
to set the rectangle dimensions in pixel for the generated iconsuseSingleColor
to only use a single color for the whole identiconuseMaterialColors
to use Material colors, they are a bit more intensive and match better with Material design stylesuseExtendedBlockConfigurator
to allow the generation of triangles and rotated rectangles instead of only blocks
.NET Client
The Dangl.Icons.Client package contains a DanglIconsServiceCollectionExtensions
class which has extension methods
to configure the clients for dependency injection. This will also attach api keys (if given) to all outgoing requests.
It uses the HttpClientFactory
and is therefore safe to use throughout the lifetime of the application.
Examples
?size=64
&useSingleColor=true
&useMaterialColors=true
&useExtendedBlockConfigurator=true
?size=64
&useSingleColor=false
&useMaterialColors=true
&useExtendedBlockConfigurator=true
?size=64
&useSingleColor=true
&useMaterialColors=true
&useExtendedBlockConfigurator=false
?size=64
&useSingleColor=false
&useMaterialColors=false
&useExtendedBlockConfigurator=true
Docker Build
To build a Docker image, run ./build.ps1 BuildDocker -Configuration Release
in the root directory of the solution. A build tagged danglicons:dev
will be created
Assembly Strong Naming & Usage in Signed Applications
This module produces strong named assemblies when compiled. When consumers of this package require strongly named assemblies, for example when they
themselves are signed, the outputs should work as-is.
The key file to create the strong name is adjacent to the csproj
file in the root of the source project. Please note that this does not increase
security or provide tamper-proof binaries, as the key is available in the source code per
Microsoft guidelines