Repository files navigation

.NET wrapper around theLibSass library with the ability to support a virtual file system.

This library can be installed through NuGet.LibSassHost package does not contain the native implementations of the LibSass.Therefore, you need to choose and install the most appropriate package(s) for your platform.The following packages are available:

• LibSassHost.Native.win-x86 contains the native assembly for Windows (x86).
• LibSassHost.Native.win-x64 contains the native assembly for Windows (x64).
• LibSassHost.Native.win-arm contains the native assembly for Windows (ARM).
• LibSassHost.Native.win-arm64 contains the native assembly for Windows (ARM64).
• LibSassHost.Native.linux-x64 contains the native assembly for Linux (x64). Only compatible with .NET Core.
• LibSassHost.Native.osx-x64 contains the native assembly for OS X (x64). Only compatible with .NET Core.

If you need support for other operating systems, then you should read the“Building LibSass” section.

LibSassHost.Native.linux-x64 and LibSassHost.Native.osx-x64 packages do not support installation underMono, but you can to install the native assemblies manually.

First you need to get thelibsass.so assembly file. You have 3 ways to do this:

1. Download a assembly file from the LibSass Host's project repository.
2. Extract a assembly file from theLibSassHost.Native.linux-x64 package. Thelibsass.so file is located in theruntimes/linux-x64/native/ directory of NuGet package.
3. Build a assembly file from the source code.

Afterwards open a terminal window and change directory to the directory where thelibsass.so file is located. Next, enter the following command:

sudo cp libsass.so /usr/local/lib/sudo ldconfig

First you need to get thelibsass.dylib assembly file. You have 3 ways to do this:

1. Download a assembly file from the LibSass Host's project repository.
2. Extract a assembly file from theLibSassHost.Native.osx-x64 package. Thelibsass.dylib file is located in theruntimes/osx-x64/native/ directory of NuGet package.
3. Build a assembly file from the source code.

Afterwards open a terminal window and change directory to the directory where thelibsass.dylib file is located. Next, enter the following command:

mkdir -p /usr/local/lib/ && cp libsass.dylib "$_"

The main difference between this library from other .NET wrappers around the LibSass (e.g.libsassnet,SharpScss,NSass,Sass.Net) is ability to support a virtual file system. You can set the file manager by usingFileManager property of theSassCompiler class:

SassCompiler.FileManager=CustomFileManager();

Any class, that implements anIFileManager interface, can be used as a file manager.By default, file manager is not specified, and for access to the file system are used built-in tools of the LibSass library.The main advantage of using built-in tools is the low memory consumption.But there is a disadvantage: there is no ability to process files in UTF-16 encoding.

To resolve this disadvantage you need to use theFileManager class:

SassCompiler.FileManager=FileManager.Instance;

But in this case, will increase memory consumption (approximately 3 times).

A good example of implementing a custom file manager, which provides access to the virtual file system, is theVirtualFileManager class from theBundleTransformer.SassAndScss package.

It should also be noted, that this library does not write the result of compilation to disk.Compile andCompileFile methods of theSassCompiler class return the result of compilation in the form of an instance of theCompilationResult class. Consider in detail properties of theCompilationResult class:

Consider a simple example of usage of theCompile method:

usingSystem;usingLibSassHost;usingLibSassHost.Helpers;namespaceLibSassHost.Example.ConsoleApplication{classProgram{staticvoidMain(string[]args){conststringinputContent=@"$font-stack:    Helvetica, sans-serif;$primary-color: #333;body {  font: 100% $font-stack;  color: $primary-color;}";try{varoptions=newCompilationOptions{SourceMap=true};CompilationResultresult=SassCompiler.Compile(inputContent,"input.scss","output.css","output.css.map",options);Console.WriteLine("Compiled content:{1}{1}{0}{1}",result.CompiledContent,Environment.NewLine);Console.WriteLine("Source map:{1}{1}{0}{1}",result.SourceMap,Environment.NewLine);Console.WriteLine("Included file paths: {0}",string.Join(", ",result.IncludedFilePaths));}catch(SassCompilationExceptione){Console.WriteLine("During compilation of SCSS code an error occurred. See details:");Console.WriteLine();Console.WriteLine(SassErrorHelpers.GenerateErrorDetails(e));}}}}

First we call theCompile method ofSassCompiler class with the following parameters:

1. content - text content written on Sass/SCSS.
2. inputPath - path to input Sass/SCSS file. Needed for generation of source map.
3. outputPath (optional) - path to output CSS file. Needed for generation of source map. If path to output file is not specified, but specified a path to input file, then value of this parameter is obtained by replacing extension in the input file path by.css extension.
4. sourceMapPath (optional) - path to source map file. If path to source map file is not specified, but specified a path to output file, then value of this parameter is obtained by replacing extension in the output file path by.css.map extension.
5. options (optional) - compilation options (instance of theCompilationOptions class)

Then output result of compilation to the console. In addition, we provide handling of theSassCompilationException exception.

And now let's consider in detail properties of theCompilationOptions class:

Using of theCompileFile method quite a bit different from using of theCompile method:

usingSystem;usingSystem.IO;usingLibSassHost;usingLibSassHost.Helpers;namespaceLibSassHost.Example.ConsoleApplication{classProgram{staticvoidMain(string[]args){conststringbasePath="/Projects/TestSass";stringinputFilePath=Path.Combine(basePath,"style.scss");stringoutputFilePath=Path.Combine(basePath,"style.css");stringsourceMapFilePath=Path.Combine(basePath,"style.css.map");try{varoptions=newCompilationOptions{SourceMap=true};CompilationResultresult=SassCompiler.CompileFile(inputFilePath,outputFilePath,sourceMapFilePath,options);Console.WriteLine("Compiled content:{1}{1}{0}{1}",result.CompiledContent,Environment.NewLine);Console.WriteLine("Source map:{1}{1}{0}{1}",result.SourceMap,Environment.NewLine);Console.WriteLine("Included file paths: {0}",string.Join(", ",result.IncludedFilePaths));}catch(SassCompilationExceptione){Console.WriteLine("During compilation of SCSS file an error occurred. See details:");Console.WriteLine();Console.WriteLine(SassErrorHelpers.GenerateErrorDetails(e));}}}}

In this case, theinputPath parameter is used instead of thecontent parameter. Moreover, value of theinputPath parameter now should contain the path to real file.

LibSassHost uses a modified version of the LibSass library.In most cases, you do not need to build the LibSass from source code, because the native assemblies is published asLibSassHost.Native.* NuGet packages.The only exception is the case, when you want to build library for a specific Linux distro.

To build a modified version of the LibSass you must first clone the LibSassHost repository:

mkdir Github && cd Githubgit clone https://github.com/Taritsyn/LibSassHost.git

Further actions depend on your operating system.

In your system must be installed Visual Studio 2019 or 2022 with C++ support.

To build the LibSass on Windows:

1. Openlibsass.sln in Visual Studio.
2. Select theConfiguration and targetPlatform, and build the solution.
3. Build output will be undersrc\libsass\bin\[Debug|Release]\[Win32|x64].

Alternatively, you can use the build script.Open a Visual Studio developer command prompt and run thebuild-libsass.cmd script from yourLibSassHost project directory:

C:\Users\username\Github\LibSassHost> build-libsass

Build script can also take a options, information about which can be obtained by using the following command:

build-libsass /?

In your system must be installed GCC (GNU Compiler Collection).In every Linux distro installation of GCC is made in different ways.For example, in Ubuntu 16.04 this is done as follows:

sudo apt-get updatesudo apt-get install build-essential

To build the LibSass on Linux open a terminal window and run thebuild-libsass.sh script from yourLibSassHost project directory:

username@ubuntu-16:~/Github/LibSassHost$ ./build-libsass.sh

Build output will be undersrc/libsass/bin/[Debug|Release]/Linux.

Build script can also take a options, information about which can be obtained by using the following command:

./build-libsass.sh --help

In your system must be installed Xcode Command Line Tools.To install Xcode Command Line Tools, in your terminal simply run:

xcode-select --install

To build the LibSass on OS X open a terminal window and run thebuild-libsass.sh script from yourLibSassHost project directory:

My-Mac:LibSassHost username$ ./build-libsass.sh

Build output will be undersrc/libsass/bin/[Debug|Release]/OSX.

Build script can also take a options, information about which can be obtained by using the following command:

./build-libsass.sh --help

If you use the LibSass Host for .NET in some project, please send me a message so I can include it in this list:

• Abstractions Sass Compiler CI Build by Abstractions AS
• Abstractions Sass Compiler Visual Studio Extension by Abstractions AS
• Abstractions SASS Theming System by Abstractions AS
• Core Sass Compiler by Ben Mills
• CssBuilder
• JacobDixon.AspNetCore.LiveSassCompile by Jacob Dixon
• Karambolo.AspNetCore.Bundling by Adam Simon
• LibSassBuilder by Johan van Rensburg
• MustardBlack-Core.Assets.Css.Sass by Andrew Bullock
• Profound.Kentico.SassPlugin by Arindam Debnath
• Sass.AspNetCore by Aleksandr Ovchinnikov
• Virto Commerce Storefront Kit by Virto Solutions LTD