VNS.Umbraco 17.2.0

VNS Umbraco

Some different helper tools for Umbraco Core

Installation

Use the package manager nuget to install.

dotnet add package VNS.Umbraco

Intro

This package includes a custom composer that registers the VNS.Umbraco helper services and provides enhanced content finding capabilities for Umbraco 17+.

public class UpdateContentFindersComposer: IComposer {
	public void Compose(IUmbracoBuilder builder) {
		// Set Error404Finder as the last chance content finder
		builder.SetContentLastChanceFinder<Error404Finder>();

		// Append TemplateFinder to the existing content finders
		builder.ContentFinders().Append<TemplateFinder>();

		// Register Helper as scoped service
		builder.Services.AddScoped<Helper>();
	}
}

TemplateFinder

This content finder matches URLs to template names and applies them to content nodes. It intelligently handles both simple template routing and content+template combinations:

• Template routing: Accessing /SiteMap will look for a template named "SiteMap" and display the root content with that template applied
• Content + Template: Accessing /about/SiteMap will look for content at /about/ and apply the "SiteMap" template to it
• If a content node exists at the exact URL path, it takes precedence and uses that content with the specified template

This replaces Umbraco's deprecated ContentFinderByUrlAndTemplate with a solution that works reliably in Umbraco 17+.

Error404Finder

This content finder serves as the last chance fallback when no other content finder has matched a request. It will search for a page in the content tree that either:

• Has the name "Error404" (not case sensitive), or
• Has a property with alias "errorCode" containing the value "404"

This finder is registered using SetContentLastChanceFinder to ensure it only runs when all other content finders have failed.

Init

Add this to the top of your template

// Using
@using VNS.Umbraco;

// For injection
@inject VNS.Umbraco.Helper _vns;

Helper

Injection is required

// Get translation label
string _vns.GetTranslation(string name, string culture = "", string altText = "")

// Get the raw SVG from IPublishedContent
string _vns.GetSVG(IPublishedContent media);

Util (Utility)

This contains a lot of different small static methods to help you create simple code

// Get httpcontext
HttpContext Util.ctx;

// Get appsettings (Will load from appsettings.json)
IConfigurationRoot Util.AppSettings;

// Get connection provider (Will return connection provider named umbracoDbDSN_ProviderName)
string Util.ConnectionProvider;

// Get current culture
string Util.CurrentCulture;

// Get connectionstring (Will return connectionstring named umbracoDbDSN)
string Util.ConnectionString;

// Get smtp (Will return from Umbraco:CMS:Global:Smtp)
IConfigurationSection Util.Smtp;

// Get remote IP (With cloudflare support - Using CF-Connecting-IP header if behind CF)
string Util.RemoteIP;

// Get status code
int Util.StatusCode;

// Get request method
string Util.ReqMethod;

// Is request method post
bool Util.IsPost;

// Get current url
string Util.GetCurrentUrl(bool includePath = true, bool includeQueryString = false);

// Request from form/querystring
string Util.Req(string key);

// Request from form
string Util.ReqForm(string key);

// Request from querystring
string Util.ReqQuery(string key);

// Get culture-specific text from JSON array
// Expects JSON format: [{"culture":"da-DK","text":"Danish text"},{"culture":"en-US","text":"English text"}]
// Returns text for specified culture, or current culture if not specified
// Commonly used with VNS.MultiLanguageTextbox plugin (https://github.com/schlagerdk/VNS.MultiLanguageTextbox)
string Util.GetCultureText(string cultureJson, string culture = null);
string Util.GetCultureText(object cultureJson, string culture = null);

// IPGeo (If no IP is set, RemoteIP will be used)
string Util.IPGeo(string ip = "");

// Domain whois (Currently only .com domains)
string Util.Whois(string domain);

// Request headers
IHeaderDictionary Util.ReqHeaders;

// Request header
StringValues Util.ReqHeader(string key);

// Request header
string Util.ReqHead(string key, bool htmlDecode = false);

// Request referer
string Util.ReqRef;

// Request host
string Util.ReqHost;

// Request user-agent
string Util.ReqUserAgent;

// Is host in ref
bool Util.IsHostInRef;

// Url Encode/Decode
string Util.UrlEncode(string value);
string Util.UrlDecode(string value);

// Html Encode/Decode
string Util.HtmlEncode(string value);
string Util.HtmlDecode(string value);

// Write to body
void Util.Write(object message);

// WriteBOM - Will write \uFEFF to body
void Util.WriteBOM();

// Redirect
void Util.Redirect(string url);

// Will try to add to header
bool Util.Add2Header(string key, StringValues value);

// Will try to add "Content-Disposition" to the header key and "attachment;filename={value}" to value
bool Util.SetContentFilename(string value);

// Set content type
void Util.SetContentType(string contentType);

// Check if dynamic object contains a key
bool Util.ContainsKey(dynamic obj, string key);

// Session
void Util.SetSession(string key, object value);
T Util.GetSession<T>(string key);
void Util.RemoveSession(string key);
void Util.ClearSession();

// Cookie
void Util.SetCookie(string key, object value, DateTime? expires = null)
T Util.GetCookie<T>(string key);
void Util.DeleteCookie(string key);

// Udi
Udi Util.GetUdi(this IPublishedContent content);

// Render view as string
string Util.RenderViewAsString(Microsoft.AspNetCore.Html.IHtmlContent partial, System.Text.Encodings.Web.HtmlEncoder encoder);

// Get request files
IFormCollection Util.ReqFiles

// Get request file
IFormFile Util.ReqFile(string name);

// Save file
bool Util.SaveFile(IFormFile file, string path);
Task<bool> Util.SaveFileAsync(IFormFile file, string path);

// Convert file to base64
string Util.ConvertToBase64(this IFormFile file);
Task<string> Util.ConvertToBase64Async(this IFormFile file);

// Posted body
System.IO.Stream Util.ReqBody();
string Util.ReqBodyAsString();
Task<string> Util.ReqBodyAsStringAsync();

// Convert to XDocument
XDocument Util.Json2Xml(string json, string root = "");
XDocument Util.Obj2Xml(object obj, string root = "");

// Convert to JSON
string Util.Obj2Json(object obj);
string Util.Xml2Json(string xml);
string Util.CSV2Json(string path, string delimiter = ";");

// Convert to dynamic
T Util.Xml2Dynamic<T>(string xml);
T Util.Json2Dynamic<T>(string json);
T Util.Obj2Dynamic<T>(object obj);

// Convert stream
string Util.StreamToString(System.IO.Stream stream);
Task<string> Util.StreamToStringAsync(System.IO.Stream stream);
string Util.Stream2String(System.IO.Stream stream);

// Send email (Will use smtp settings from appsettings, will look for UserName, Password and add from object from Name parameter in smtp selection to use as from name if fromName parameter not set)
bool Util.SendEmail(System.Net.Mail.MailMessage mailMessage, bool forceSecure);
bool Util.SendEmail(System.Net.Mail.MailMessage mailMessage, string fromName = "", bool forceSecure = false);
Task<bool> Util.SendEmailAsync(System.Net.Mail.MailMessage mailMessage, bool forceSecure);
Task<bool> Util.SendEmailAsync(System.Net.Mail.MailMessage mailMessage, string fromName = "", bool forceSecure = false);

// This will just prettify json with indents for better display on web
string Util.FormatJson(Newtonsoft.Json.Linq.JObject json, bool fix4Web = false);
string Util.FormatJson(string json, bool fix4Web = false);

// Combine objects
object Util.CombineObj(object obj1, object obj2, object obj3 = null, object obj4 = null);

// Convert UnixTime to datetime
DateTime Util.DateFromUnixTime(long unixdate);

// Expose object
void Util.DrillObject(object obj);

// Clone object
T Util.CloneObj<T>(T obj);

// Clean HTML
string Util.CleanHtml(string html);

Secy (Security)

This contains a lot of different small static methods to help you create simple code

// Generate random password
string Secy.GeneratePassword(int passwordLength = 10);

// Hash (MD5, SHA256, or SHA512)
string Secy.Hash(string text, bool Use256 = false, bool Use512 = false);
string Secy.Hash256(string text);
string Secy.Hash512(string text);

// ASCII to Base64
string Secy.A2B(string input);

// Base64 to ASCII
string Secy.B2A(string input);

// Encrypt Text
string Secy.EncryptText(string text, string secret = "");

// Decrypt Text
string Secy.DecryptText(string text, string secret = "");

// Generate JWT token
string Secy.GetToken(object payload, string serectKey = "", int expireAfterMinutes = 1440, int notValidBeforeMinutes = 0);

// Check if JWT token is valid
bool Secy.IsTokenValid(string token, string serectKey, out string message);

// Get token headers from JWT
dynamic Secy.GetTokenHeaders(string token);

// Get token payload from JWT
dynamic Secy.GetTokenPayload(string token);

Soap

Helper class for making SOAP requests

// Init
var soap = new SOAP(string url, string xmlns = "");

// Get / Set properties
Dictionary<string, string> soap.Headers;

// Execute SOAP request
string soap.Execute(string method, string payloadXml = "");
Task<string> soap.ExecuteAsync(string method, string payloadXml = "");

// Result status
int soap.StatusCode;
string soap.StatusDescription;
bool soap.IsSuccess;

Rest

Helper class for making REST API requests with support for various authentication methods

// Init
var rest = new REST();
// Init with token
var rest = new REST(string token);
// Or init with basic authentication
var rest = new REST(string login = "", string password = "", string seperator = ":", string prefix = "Basic");

// Get / Set properties
string rest.ContentType; // Default: "application/json"
string rest.Accept; // Accept header
string rest.Method; // HTTP method (GET, POST, PUT, DELETE, etc.)
string rest.BaseUrl; // Base URL for all requests
bool rest.KeepAlive; // Keep connection alive (Default: true)
bool rest.IgnoreSSL; // Ignore SSL certificate validation (Default: false)
int rest.Timeout; // Request timeout in seconds (Default: 100)
Dictionary<string, string> rest.Headers; // Custom headers

// Execute with HttpContent (synchronous)
string rest.Execute(string url, HttpContent content = null);

// Execute with string payload (synchronous)
string rest.Execute(string url, string payload);

// Execute with string payload as multipart (synchronous)
string rest.Execute(string url, string payload, bool asMultipart);

// Execute with HttpContent (asynchronous)
Task<string> rest.ExecuteAsync(string url, HttpContent content = null);

// Execute with string payload (asynchronous)
Task<string> rest.ExecuteAsync(string url, string payload);

// Execute with string payload as multipart (asynchronous)
Task<string> rest.ExecuteAsync(string url, string payload, bool asMultipart);

// Example with JSON string:
var rest = new REST("token");
rest.BaseUrl = "https://api.example.com";
var json = Util.Obj2Json(new { name = "John", age = 30, fileBase64 = "iVBORw0KG..." });
var response = rest.Execute("/users", json);

// Example with JSON converted to multipart:
var rest = new REST("token");
rest.BaseUrl = "https://api.example.com";
var json = Util.Obj2Json(new { name = "John", age = 30, fileBase64 = "iVBORw0KG..." });
var response = rest.Execute("/users", json, asMultipart: true);

// Example with MultipartFormDataContent:
var rest = new REST("token");
rest.BaseUrl = "https://api.example.com";
var multipart = new MultipartFormDataContent();
multipart.Add(new StringContent("John"), "name");
multipart.Add(new StringContent("30"), "age");
multipart.Add(new ByteArrayContent(fileBytes), "file", "filename.jpg");
var response = rest.Execute("/users", multipart);

// Result status
int rest.StatusCode;
string rest.StatusDescription;
bool rest.IsSuccess;

SQL

Helper class for SQL Server database operations

// Init with connection string
var sql = new SQL(string connectionString, bool trustServerCertificate = true, bool encrypt = true);
// Or init with server credentials
var sql = new SQL(string server, string database, string login, string password, bool trustServerCertificate = true, bool encrypt = true);

// Properties:
// - trustServerCertificate: Set to true to bypass SSL certificate validation (Default: true)
// - encrypt: Set to false to disable encryption (Default: true)

// Example with certificate trust for development:
var sql = new SQL("Server=localhost;Database=mydb;User Id=sa;Password=pass;");

// Select data from SQL
var reader = sql.GetReader(string sql);

// Loop reader
while(reader.Read()){
	// Do stuff
}

// Close reader
reader.Close();

// Insert, Update, Delete etc.
void sql.Execute(string sql);

// Close sql
sql.Close();

SQLite

Helper class for SQLite database operations

// Init with connection string
var sqlite = new SQLite(string connectionString);
// Or init with data source and options
var sqlite = new SQLite(string dataSource, bool foreignKeys, bool pooling);

// Select data from SQL
var reader = sqlite.GetReader(string sql);

// Loop reader
while(reader.Read()){
	// Do stuff
}

// Close reader
reader.Close();

// Insert, Update, Delete etc.
void sqlite.Execute(string sql);

// Close sql
sqlite.Close();

Cookiebot

Helper class for reading Cookiebot consent preferences

// Init
var cookiebot = new Cookiebot(string cookieName = "CookieConsent", string preferencesName = "preferences", string statisticsName = "statistics", string marketingName = "marketing");

// Properties
bool cookiebot.Necessary;
bool cookiebot.Statistics;
bool cookiebot.Marketing;
bool cookiebot.Preferences;

Log

Logging functionality for different log levels. Injection is required.

_vns.Log.Trace(string message, Exception ex = null);
_vns.Log.Debug(string message, Exception ex = null);
_vns.Log.Info(string message, Exception ex = null);
_vns.Log.Warning(string message, Exception ex = null);
_vns.Log.Error(string message, Exception ex = null);
_vns.Log.Fatal(string message, Exception ex = null);

Content

Helper methods for managing Umbraco content nodes. Injection is required.

// Create a node
IContent _vns.Content.Create(string name, int parent, string documentTypeAlias, Dictionary<string, object> keyValues = null, string[] cultures = null);

// Get a node
IContent _vns.Content.Get(int id);

// Copy node
void _vns.Content.Copy(IContent content, int parentId);

// Move node
void _vns.Content.Move(IContent content, int parentId);

// Get schedule collection
ContentScheduleCollection _vns.Content.GetScheduleCollection(IContent content);

// Get release date
DateTime _vns.Content.GetReleaseDate(IContent content);

// Set release date - Will set the schedule and save the node
void _vns.Content.SetReleaseDate(IContent content, DateTime releaseDate)

// Get expire date
DateTime _vns.Content.GetExpireDate(IContent content);

// Set expire date - Will set the schedule and save the node
void _vns.Content.SetExpireDate(IContent content, DateTime expireDate)

// Unpublish node
void _vns.Content.Unpublish(IContent content);

// Save node
void _vns.Content.Save(IContent content, ContentScheduleCollection contentScheduleCollection = null);

// Save and publish node
void _vns.Content.SaveAndPublish(IContent content, string[] cultures = null);

// Delete node
void _vns.Content.Delete(int id);

Member

Helper methods for managing Umbraco members, authentication, and roles. Injection is required.

// Properties for current member
bool _vns.Member.IsLoggedIn;
int _vns.Member.Id;
string _vns.Member.Username;
string _vns.Member.Name;
string _vns.Member.Email;
string _vns.Member.Comments;
DateTime? _vns.Member.LastLoginDate;

// SignOut
void _vns.Member.SignOut();

// Validate
bool _vns.Member.Validate(string userName, string password);

// Create member
IdentityResult result = _vns.Member.Create(string name, string email, string password, bool isApproved = true);
IdentityResult result = _vns.Member.Create(string name, string email, string userName, string password, bool isApproved, string memberTypeAlias = "Member");

// IdentityResult properties
bool result.Succeeded;
IEnumerable<T> result.Errors;

// Login
SignInResult result = _vns.Member.Login(string userName, string password);

// SignInResult properties
bool result.IsLockedOut;
bool result.IsNotAllowed;
bool result.RequiresTwoFactor;

// Lock / Unlock
void _vns.Member.Lock(IMember member);
void _vns.Member.Unlock(IMember member);

// Exists
bool _vns.Member.Exists(string userName);
bool _vns.Member.EmailExists(string email);

// Get a member
IMember _vns.Member.Get(); // Will return current loggedin member
IMember _vns.Member.Get(int id);
IMember _vns.Member.Get(Guid key);
IMember _vns.Member.Get(string userName);
IMember _vns.Member.GetByEmail(string email);

// Get multiple members
IEnumerable<IMember> _vns.Member.GetAllMembers(params int[] ids);
IEnumerable<IMember> _vns.Member.GetMembersByMemberType(string memberTypeid)

// Get Types
IEnumerable<IMemberType> _vns.Member.GetAllMembertypes();

// Get Roles
IEnumerable<IMemberGroup> _vns.Member.GetAllRoles();
IEnumerable<string> _vns.Member.GetAllRoles(int memberid);

// Generate password
string _vns.Member.GeneratePassword();

// Reset password
string _vns.Member.ResetPassword(string email);

// Change password
IdentityResult result = _vns.Member.ChangePassword(string oldPassword, string newPassword);

// IdentityResult properties
bool result.Succeeded;
IEnumerable<T> result.Errors;

// Save member
void _vns.Member.Save(IMember member);

// Delete member
void _vns.Member.Delete(int id);
void _vns.Member.Delete(string userName);
void _vns.Member.Delete(IMember member);

License

MIT