Blazicons.Generating 3.3.35

Blazicons.Generating

Provides support for generating Blazicon library packages.

See the changelog for change history.

Overview

Blazicons.Generating is a library designed to assist in generating code for Blazicon icon library implementations. It does this by providing helper classes for reading the source repositories of open-source font libraries and for the generation of Blazicon libraries.

Getting Started

Installation

Add a reference to the Blazicons.Generating package in your project.

Basic Configuration

Configure your .csproj file with the required properties to generate icon classes:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <BlaziconsRepoUrl>https://github.com/example/icons/archive/refs/heads/main.zip</BlaziconsRepoUrl>
    <BlaziconsSvgPattern>^src\/svg\/.*.svg$</BlaziconsSvgPattern>
    <BlaziconsClassName>MyIcon</BlaziconsClassName>
    <BlaziconsSvgFolderPath>src/svg</BlaziconsSvgFolderPath>
    <BlaziconsPropertyNameRemovalPatterns>^My_Icon_;_24_\w*$;-(original|plain|line)</BlaziconsPropertyNameRemovalPatterns>
    <BlaziconsSkipColorScrub>true</BlaziconsSkipColorScrub>
    <BlaziconsGeneratedCodeOutputPath>Generated</BlaziconsGeneratedCodeOutputPath>
    <BlaziconsGeneratorPath>MyIcons.Generating/MyIcons.Generating.MyIconsGenerator</BlaziconsGeneratorPath>
  </PropertyGroup>
</Project>

Property Name Transformation Examples:

Patterns are applied in order. Use regex anchors to control where matching occurs:

• ^pattern - Removes from the start (prefix removal)
• pattern$ - Removes from the end (suffix removal)
• pattern - Removes anywhere in the filename

Example with the above configuration:

• Ic_Fluent_Activity_24_regular.svg → Activity (prefix ^Ic_Fluent_ removed, then suffix _24_\w*$ removed)
• Ic_Fluent_Person_24_filled.svg → Person (prefix ^Ic_Fluent_ removed, then suffix _24_\w*$ removed)
• react-plain.svg → React (pattern -(original|plain|line) removed)
• angular-original.svg → Angular (pattern -(original|plain|line) removed)

Configuration Properties

* Either BlaziconsRepoUrl or BlaziconsRepoPath must be specified.

Advanced Configuration

Generating Multiple Icon Classes

For cases where multiple icon sets are desired in one package (e.g., different aspect ratios or styles), the recommended approach is to create separate non-packable generator projects that output to your main project.

my-icons/
├─ MyIcons.csproj (main project, packable)
├─ MyIcons.Filled/
│ ├─ MyIcons.Filled.csproj (generator project, non-packable)
├─ MyIcons.Outlined/
│ ├─ MyIcons.Outlined.csproj (generator project, non-packable)

Build-Time Generation Control

Code generation is controlled by the BlaziconsEnableCodeGeneration property, which is automatically set based on configuration file presence. To manually control generation:

<PropertyGroup>
  <BlaziconsEnableCodeGeneration>true</BlaziconsEnableCodeGeneration>
</PropertyGroup>

Debugging Path Issues

When experiencing "SVG folder not found" errors, use the BlaziconsPreserveExtractedFiles property to preserve temporary files for inspection:

<PropertyGroup>
  <BlaziconsPreserveExtractedFiles>true</BlaziconsPreserveExtractedFiles>
</PropertyGroup>

Build the project and check the build output for the message "Extracted files preserved at: [path]". You can then navigate to that directory to verify the folder structure and determine the correct BlaziconsSvgFolderPath value. Remember to set this property back to false for production builds.

Troubleshooting

Code not generating

1. Ensure BlaziconsEnableCodeGeneration is set to true
2. Verify all required properties are configured
3. Check that the BlaziconsRepoUrl or BlaziconsRepoPath is valid and accessible
4. Review build output for error messages from the generator

SVG folder not found

1. Use BlaziconsPreserveExtractedFiles set to true to keep temporary extracted files
2. Check the build output for the "Extracted files preserved at" message
3. Navigate to that directory to verify the actual folder structure
4. Adjust BlaziconsSvgFolderPath to match the relative path from the extracted files root
5. Remember to set BlaziconsPreserveExtractedFiles back to false for normal use

Build errors after generation

1. Clean the solution and rebuild
2. Verify the generated code is in the expected output directory
3. Ensure the target frameworks match your project requirements