This package provides a comprehensive collection of common helpers, utilities, and extensions for Xperience by Kentico projects. The package includes encryption helpers, text manipulation utilities, collection extensions, localization helpers, and URL utilities designed to streamline development and reduce boilerplate code in Xperience applications.
| Xperience Version | Library Version |
|---|---|
| >= 30.6.0 | >= 1.0.0 |
Note: The latest version that has been tested is 30.6.0
Add the package to your application using the .NET CLI
dotnet add package XperienceCommunity.EssentialsOnce the package is installed, you need to initialize the ConfigurationHelper in your Program.cs file to enable configuration-dependent features like AES encryption:
// Add this line in your Program.cs after building the configuration
ConfigurationHelper.Initialize(builder.Configuration);After initialization, the helpers and extensions will be automatically available in your Xperience application. Most features work out of the box, with optional configuration available for specific helpers like the AES encryption.
The package supports optional configuration for certain features. Add the following section to your appsettings.json:
{
"XperienceCommunityEssentials": {
"AesSecureKey": ""
}
}| Setting | Description | Required |
|---|---|---|
AesSecureKey |
Base64 encoded key for AES encryption/decryption operations | Yes (when using AesEncryptionHelper) |
Secure encryption and decryption: Provides AES encryption capabilities with configurable keys for securing sensitive data.
EncryptAes(string plainText)- Encrypts plain text using AES with CBC modeDecryptAes(string cipherText)- Decrypts AES encrypted text back to plain textGetMd5Hash(string input)- Generates MD5 hash of input string
Configuration Required: You must set the AesSecureKey in your appsettings.json to use this helper.
String manipulation utilities: A comprehensive set of extension methods for common text operations.
Truncate(int maxLength, string truncationSuffix = "…")- Truncates strings with optional suffixEncodeToBase64()/DecodeFromBase64()- Base64 encoding/decodingGenerateId(int length = 10)- Generates random ID stringsCleanHtml()- Removes HTML tags and cleans text contentReplaceSpecialChars()- Replaces special characters for URL-safe stringsEscapeMarkdown()- Escapes markdown special charactersExtractFileNameToTitleCase()- Converts file paths to title case namesCleanPhoneNumber()- Formats and cleans phone numbers
Enhanced enumerable operations: Useful extension methods for working with collections.
ContainsAny(IEnumerable<string> target)- Checks if any source elements exist in targetHasAnyMatch(IEnumerable<string> target)- Bidirectional containment checkGetFirstOrDefault<T, TResult>(Func<T, TResult> selector, TResult defaultValue)- Safe property access with defaultsGetFirstOrEmpty<T>(Func<T, string> selector)- Gets first string value or empty string
Enhanced localization helpers: Improved localization with fallback support.
IStringLocalizer.GetStringOrDefault(string name, string defaultValue)- Gets localized string with fallbackIHtmlLocalizer.GetHtmlStringOrDefault(string name, HtmlString defaultValue)- Gets localized HTML with fallback
URL manipulation utilities: Helper methods for working with Xperience page URLs.
RelativePathTrimmed()- Gets relative path without tilde prefixAbsoluteURL(HttpRequest currentRequest)- Converts relative URLs to absolute URLs- String extension for relative URL to absolute URL conversion
Enum-based dropdown data provider: Generic provider for populating dropdown components with enum values in the Xperience admin interface.
EnumDropDownOptionsProvider<T>- Generic provider that converts enum values to dropdown optionsParse(string rawValue, T defaultValue)- Static helper method to parse stored string values back to enum type with fallback
Usage Example:
// Define your enum
public enum GridLayoutOptions
{
[Description("1 Column")]
OneColumn = 1,
[Description("2 Columns")]
TwoColumns = 2,
[Description("3 Columns")]
ThreeColumns = 3
}
// Use in a page builder or form component property
[DropDownComponent(
Label = "# of columns",
DataProviderType = typeof(EnumDropDownOptionsProvider<GridLayoutOptions>),
Order = 1)]
public string Columns { get; set; } = GridLayoutOptions.TwoColumns.ToString();Centralized configuration access: Provides global access to application configuration.
Initialize(IConfiguration configuration)- Initialize the helper with configurationSettings- Static property for accessing configuration throughout the application
// Encrypt sensitive data
string encrypted = EncryptionHelper.EncryptAes("sensitive information");
// Decrypt data
string decrypted = EncryptionHelper.DecryptAes(encrypted);
// Generate hash
string hash = AesEncryptionHelper.GetMd5Hash("password");// Truncate long text
string truncated = longText.Truncate(100);
// Clean HTML content
string cleanText = htmlContent.CleanHtml();
// Generate a unique ID
string id = someNumber.GenerateId(12);
// Encode to Base64
string encoded = text.EncodeToBase64();
// Convert letters to numbers on phone numbers
string converted = TextHelper.PhoneNumberLettersToNumbers("800-123-TEXT");// Check for any matches
bool hasMatch = sourceList.ContainsAny(targetList);
// Safe property access
var identifier = assetCollection.GetFirstOrEmpty(a => a.Identifier);
var url = assetCollection.GetFirstOrEmpty(a => a.AssetFile.Url);
var name = assetCollection.GetFirstOrEmpty(a => a.AssetFile.Metadata.Name);
var count = assetCollection.GetFirstOrDefault(a => a.SomeIntProperty, 0);
var date = assetCollection.GetFirstOrDefault(a => a.SomeDateTime, DateTime.MinValue);// Convert to absolute URL
string absoluteUrl = pageUrl.AbsoluteURL(HttpContext.Request);
// Clean relative path
string cleanPath = pageUrl.RelativePathTrimmed();// String localization with fallback
string text = localizer.GetStringOrDefault("key", "Default Text");
// HTML localization with fallback
HtmlString html = htmlLocalizer.GetHtmlStringOrDefault("key", new HtmlString("<p>Default</p>"));Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License.