PowerToys/doc/devdocs/modules/launcher/plugins/community.valuegenerator.md

Value Generator Plugin

The Value Generator plugin is used to generate hashes for strings, to calculate base64 encodings, escape and encode URLs/URIs and to generate GUIDs of version 1, 3, 4, 5, and 7.

IComputeRequest

• Interface for a request for computation
• the bool Compute() method must populate the IsSuccessful and one of the Result and ErrorMessage fields
• The result of string ResultToString() will be used for the Result's title
• The Description field will be used for the Result's subtitle

HashRequest

• Implements IComputeRequest
• Supports the hashing algorithms from System.Security.Cryptography:
  • MD5
  • SHA1
  • SHA256
  • SHA384
  • SHA512
• If other algorithms are added to System.Security.Cryptography, they can be added to the _algorithms dictionary. InputParser.ParseInput() will need to return a HashRequest for the algorithm in the query

Base64Request

• Implements IComputeRequest
• Compute() will populate Result with the base64 encoding of the byte array passed in the constructor

Base64DecodeRequest

• Implements IComputeRequest
• Compute() will populate Result with the decoded byte array of the base64 string passed in the constructor

GUIDRequest

• Implements IComputeRequest
• Uses the GUIDGenerator class to generate or compute the requested GUID

GUIDGenerator

• Utility class for generating or calculating GUIDs
• Generating GUID versions 1, 4, and 7 is done using builtin APIs:
  • UuidCreateSequential for version 1
  • System.Guid.NewGuid() for version 4
  • System.Guid.CreateVersion7() for version 7
• Versions 3 and 5 take two parameters: a namespace and a name
• The namespace must be a valid GUID or one of the predefined ones
• The PredefinedNamespaces dictionary contains aliases for the predefined namespaces
• The name can be any string

UrlEncodeRequest

• Implements IComputeRequest
• Compute() will populate Result with the encoded url converted using HttpUtility.UrlEncode().

UrlDecodeRequest

• Implements IComputeRequest
• Compute() will populate Result with the decoded url converted using HttpUtility.UrlDecode().

DataEscapeRequest

• Implements IComputeRequest
• Compute() will populate Result with the escaped data string converted using System.Uri.EscapeDataString().

DataUnescapeRequest

• Implements IComputeRequest
• Compute() will populate Result with the unescaped data string converted using System.Uri.UnescapeDataString().

HexEscapeRequest

• Implements IComputeRequest
• Compute() will populate Result with the escaped data string converted using System.Uri.HexEscape().
• Only single characters are supported as input.

HexUnescapeRequest

• Implements IComputeRequest
• Compute() will populate Result with the unescaped data string converted using System.Uri.HexUnescape().
• Only the first hexadecimal character in the string gets unescaped. The rest of the user input is ignored.

InputParser

• It is responsible only for parsing the query from the user
• Based on the user query, the ParseInput() method must return an object that implements the IComputeRequest interface or it must throw one of FormatException or ArgumentException
• Throwing an ArgumentException should signal the fact that the query contains a mistake that the user can fix (e.g. an unsupported hash function, an invalid GUID version, an invalid namespace, etc.)

The error message will be shown to the user and no log message will be created

• Throwing a FormatException should signal either:
  • that the query may become valid, and so it does not make sense to show an error just yet (e.g. the query does not contain a request yet, a hash request without a string to hash)
  • that the query is completely invalid

The error message will not be shown to the user but a log message will be created

Adding a new value generator

1. To add a new value generator, create a folder under /src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Generators/ and inside it add a class that implements IComputeRequest.
2. Add any utility classes that are specific to the new generator inside the same folder to keep them separated from the other generators.
3. Modify the InputParser.ParseInput() to handle a request for the new generator and return an instance of the class you created in step 1