Hashids.net
1.7.0
dotnet add package Hashids.net --version 1.7.0
NuGet\Install-Package Hashids.net -Version 1.7.0
<PackageReference Include="Hashids.net" Version="1.7.0" />
paket add Hashids.net --version 1.7.0
#r "nuget: Hashids.net, 1.7.0"
// Install Hashids.net as a Cake Addin #addin nuget:?package=Hashids.net&version=1.7.0 // Install Hashids.net as a Cake Tool #tool nuget:?package=Hashids.net&version=1.7.0
Hashids
A small .NET package to generate YouTube-like IDs from numbers.
It converts numbers like 347
into strings like yr8
, or array of numbers like [27, 986]
into 3kTMd
. You can also decode those ids back. This is useful in bundling several parameters into one, hiding actual IDs, or simply using them as short string IDs.
Features
- Creates short unique ids from integers. (only positive numbers & zero)
- Generates non-sequential IDs for incremental input to stay unguessable.
- Supports single number or array of numbers. (supports
int
andlong
) - Allows custom alphabet as well as salt — so ids are unique only to you. (salt must be smaller than alphabet)
- Allows specifying minimum hash length.
- Tries to avoid basic English curse words.
NOTE: This is NOT a true cryptographic hash, since it is reversible
Installation
Install the package with NuGet
Install-Package hashids.net
Usage
Import namespace
using HashidsNet;
Encoding one number
You can pass a unique salt value so your hashes differ from everyone else's. I use "this is my salt" as an example.
var hashids = new Hashids("this is my salt");
var hash = hashids.Encode(12345);
hash
is now going to be:
NkK9
If your id is stored as a Int64
you need to use "EncodeLong".
var hashids = new Hashids("this is my salt");
var hash = hashids.EncodeLong(666555444333222L);
hash
is now going to be:
KVO9yy1oO5j
Decoding
Notice during decoding, same salt value is used:
var hashids = new Hashids("this is my salt");
numbers = hashids.Decode("NkK9");
numbers
is now going to be:
[ 12345 ]
var hashids = new Hashids("this is my salt");
numbers = hashids.DecodeLong("KVO9yy1oO5j");
numbers
is now going to be:
[ 666555444333222L ]
Decoding a single id
By default, Decode and DecodeLong will return an array. If you need to decode just one id you can use the following helper functions:
var hashids = new Hashids("this is my pepper");
number = hashids.DecodeSingle("NkK9");
number
is now going to be:
12345
var hashids = new Hashids("this is my pepper");
if (hashids.TryDecodeSingle("NkK9", out int number)) { // Decoding hash successfull. }
number
is now going to be:
12345
You can handle the exception to see what went wrong with the decoding:
var hashids = new Hashids("this is my pepper");
try
{
number = hashids.DecodeSingle("NkK9");
}
catch (NoResultException) { // Decoding the provided hash has not yielded any result. }
number
is now going to be:
12345
var hashids = new Hashids("this is my pepper");
number = hashids.DecodeSingleLong("KVO9yy1oO5j");
number
is now going to be:
666555444333222L
var hashids = new Hashids("this is my pepper");
if (hashids.TryDecodeSingleLong("NkK9", out long number)) { // Decoding hash successfull. }
number
is now going to be:
666555444333222L
var hashids = new Hashids("this is my pepper");
try
{
number = hashids.DecodeSingleLong("KVO9yy1oO5j");
}
catch (NoResultException) { // Decoding the provided hash has not yielded any result. }
number
is now going to be:
666555444333222L
Decoding with different salt
Decoding will not work if salt is changed:
var hashids = new Hashids("this is my pepper");
numbers = hashids.Decode("NkK9");
numbers
is now going to be:
[]
Encoding several numbers
var hashids = new Hashids("this is my salt");
var hash = hashids.Encode(683, 94108, 123, 5);
hash
is now going to be:
aBMswoO2UB3Sj
Decoding is done the same way
var hashids = new Hashids("this is my salt");
var numbers = hashids.Decode("aBMswoO2UB3Sj")
numbers
is now going to be:
[ 683, 94108, 123, 5 ]
Encoding and specifying minimum hash length
Here we encode integer 1, and set the minimum hash length to 8 (by default it's 0 -- meaning hashes will be the shortest possible length).
var hashids = new Hashids("this is my salt", 8);
var hash = hashids.Encode(1);
hash
is now going to be:
gB0NV05e
Decoding
var hashids = new Hashids("this is my salt", 8);
var numbers = hashids.Decode("gB0NV05e");
numbers
is now going to be:
[ 1 ]
Specifying custom hash alphabet
Here we set the alphabet to consist of: "abcdefghijkABCDEFGHIJK12345"
var hashids = new Hashids("this is my salt", 0, "abcdefghijkABCDEFGHIJK12345")
var hash = hashids.Encode(1, 2, 3, 4, 5)
hash
is now going to be:
Ec4iEHeF3
Randomness
The primary purpose of hashids is to obfuscate ids. It's not meant or tested to be used for security purposes or compression. Having said that, this algorithm does try to make these hashes unguessable and unpredictable:
Repeating numbers
var hashids = new Hashids("this is my salt");
var hash = hashids.Encode(5, 5, 5, 5);
You don't see any repeating patterns that might show there's 4 identical numbers in the hash:
1Wc8cwcE
Same with incremented numbers:
var hashids = new Hashids("this is my salt");
var hash = hashids.Encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
hash
will be :
kRHnurhptKcjIDTWC3sx
Incrementing number hashes:
var hashids = new Hashids("this is my salt");
hashids.Encode(1); // => NV
hashids.Encode(2); // => 6m
hashids.Encode(3); // => yD
hashids.Encode(4); // => 2l
hashids.Encode(5); // => rD
Encoding using a HEX string
var hashids = new Hashids("this is my salt");
var hash = hashids.EncodeHex("DEADBEEF");
hash
is now going to be:
kRNrpKlJ
Decoding to a HEX string
var hashids = new Hashids("this is my salt");
var hex = hashids.DecodeHex("kRNrpKlJ");
hex
is now going to be:
DEADBEEF
Changelog
v.1.7.0
- PR #86 - Fix for decoding hash smaller than min length setting.
- Project build targets now set to
netstandard2.0
,net6.0
,net7.0
.
v.1.6.1
- PR #76 - Fix min buffer sizes.
v.1.6.0
- PR #66 - Fixed invalid constant bug.
- PR #67 and PR #73 - Update and cleanup tests and constants.
- PR #65 - Improved performance and reduced allocations for single number decode.
v1.5.0
- PR #59 and PR #61 - Project clean up and removal of
net461
target. - PR #50 - Added support for .NET 6.
- PR #49 - Optimized methods for single number encoding.
- PR #57 - Optimized methods for single number decoding.
- PR #54 and #58 - Fixed Github Actions build and test.
- PR #55 - Removed System.Buffers dependency for .NET 5 and higher.
- PR #47 - Improved performance with
readonly
andSpan<T>
usage. - PR #60 - Reference
System.Memory
to replace internalReadOnlySpan<T>
class. - PR #63 - Array and Span usage optimizations.
- PR #62 - Documentation improvements.
1.4.1
- PR #45 - Cleanup unused nuget references and replace
Microsoft.Extensions.ObjectPool
with internal implementation.
1.4.0
- Modernized project with updated build targets now set to
net461
,net5.0
,netstandard2.0
- PR #30 - Fix floating-point math to handle large ratio of alphabet to separators.
- PR #37 - Performance and memory optimizations.
- PR #42 - Performance updates and added BenchmarkDotnet for profiling.
- PR #43 - Improved performance and reduced allocations.
- Issues #23, #32, #35 - Fix floating-point math, now replaced by Horner's method.
- Issue #27 - Allow dashes in alphabet (dashes caused issues with Regex which is not used anymore).
- Issue #21 - Fix encoding exception when decoding a character used as guard.
- Issue #29 - Added tests to confirm thread-safety.
1.3.0
- PR #26 - Support .netstandard2.0.
1.2.2
- PR #19 - Only instantiate the HEX-connected Regexes if we use any of the HEX functions. This will speed up creation of "Hashids"-instances. It is likely that most users doesn't use the HEX-functions.
1.2.1
- PR #11 - Speed up consistent shuffle with less string manipulation.
- Issue #15 - Decoding strings that contain characters not in the alphabet will now return empty array. (To conform to behaviour in the js-library).
- Issue #18 - Encoding with a negative number will now return empty string. (To conform to behaviour in the js-library).
1.2.0Added
- Added .NET Core support.
1.1.2
- Fixed issue #14 that caused HEX values to be encoded/decoded incorrectly.
1.1.1
- Accepted PR #12 that fixed an issue when encoding very many longs at the same time
1.1.0
- Added support for
long
via new functions to not introduce breaking changes.EncodeLong
for encodes.DecodeLong
for decodes.
- Added interface
IHashids
for people who want an interface to work with.
1.0.1
- The .NET 4.0 version of the package used .NET 4.5 as build target. This was fixed and a new version was pushed to nuget.
1.0.0
Several public functions marked obsolete and renamed versions added, to be more appropriate:
- Function
Encrypt()
changed toEncode()
- Function
Decrypt()
changed toDecode()
- Function
EncryptHex()
changed toEncodeHex()
- Function
DecryptHex()
changed toDecodeHex()
Hashids was designed to encode integers, primary ids at most. We've had several requests to encrypt sensitive data with Hashids and this is the wrong algorithm for that. So to encourage more appropriate use,
encrypt/decrypt
is being "downgraded" toencode/decode
.- Function
0.3.4
- The public functions are now virtual and therefor can be mocked with a mocking library.
0.3.3
- Rewrote the code to support the new hashing algorithm.
- Support for
EncryptHex
andDecryptHex
0.1.4
- Initial version of the port.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- System.Memory (>= 4.5.5)
-
net6.0
- No dependencies.
-
net7.0
- No dependencies.
NuGet packages (52)
Showing the top 5 NuGet packages that depend on Hashids.net:
Package | Downloads |
---|---|
Apprio.Enablement.Platform
Package Description |
|
Apprio.Enablement.Business.Encounters
Package Description |
|
SFA.DAS.Encoding
Encode and Decode sensitive values, reads parameters from configuration. |
|
PackUtils
Many utilities like: enumeration, hash, json (extension newtonsoft), regex, signature, string, uri, dictionary, etc |
|
Stio.HashidsNet.AspNetCore
Generate YouTube-like hashes from one or many numbers. Use hashids when you do not want to expose your database ids to the user. |
GitHub repositories (4)
Showing the top 4 popular GitHub repositories that depend on Hashids.net:
Repository | Stars |
---|---|
SparkDevNetwork/Rock
An open source CMS, Relationship Management System (RMS) and Church Management System (ChMS) all rolled into one.
|
|
neozhu/visitormanagement
helps in managing visitors visiting the institutions for various reasons. It allows visitors to check-in digitally to eliminate the tedious registeration and other paperwork. Additionally, it also keeps a track of every individual inside the campus and their timings. Institutions has guards who enter their detail in some notebooks to keep a log which are practically impossible to reconcile. It is really unpleasent and hectic for visitor to stand at the gate and give details about the visit. To ease the process of registeration, Entry-In, Entry-Out, time tracking and logging the history, this VMS can be of great use!!
|
|
Anapher/Strive
Open source video conferencing platform
|
|
Xabaril/AspNetCore.Hashids
Not predictable ids library for ASP.NET Core APIs.
|
Version | Downloads | Last updated |
---|---|---|
1.7.0 | 1,667,188 | 3/17/2023 |
1.6.1 | 1,687,725 | 6/2/2022 |
1.6.0 | 47,899 | 5/22/2022 |
1.5.0 | 237,306 | 4/2/2022 |
1.4.1 | 782,235 | 7/3/2021 |
1.4.0 | 146,564 | 5/4/2021 |
1.3.0 | 2,212,822 | 10/29/2019 |
1.2.2 | 2,308,643 | 9/14/2016 |
1.2.1 | 7,913 | 9/10/2016 |
1.2.0 | 10,998 | 9/2/2016 |
1.2.0-rc | 1,926 | 9/2/2016 |
1.1.2 | 72,633 | 9/9/2015 |
1.1.1 | 9,817 | 8/29/2015 |
1.1.0 | 6,515 | 6/29/2015 |
1.0.1 | 186,394 | 4/25/2015 |
1.0.0 | 12,507 | 9/14/2014 |
0.3.4 | 1,852 | 9/14/2014 |
0.3.3 | 2,282 | 4/22/2014 |
0.1.4 | 3,308 | 12/20/2012 |