WwwFormUrlDecoder WwwFormUrlDecoder WwwFormUrlDecoder WwwFormUrlDecoder Class

Definition

Parses a URL query string, and exposes the results as a read-only vector (list) of name-value pairs from the query string.

public : sealed class WwwFormUrlDecoder : IIterable, IVectorView, IWwwFormUrlDecoderRuntimeClasspublic sealed class WwwFormUrlDecoder : IEnumerable, IReadOnlyList, IWwwFormUrlDecoderRuntimeClassPublic NotInheritable Class WwwFormUrlDecoder Implements IEnumerable, IReadOnlyList, IWwwFormUrlDecoderRuntimeClass// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Use the WwwFormUrlDecoder class to parse a query string into name-value pairs, based on the number and placement of "&" and "=" symbols. Each name-value pair is represented by an IWwwFormUrlDecoderEntry object, which has a Name property and a Value property (both strings).

Use GetFirstValueByName to find a specific named query string parameter. All languages can use this method. You'd typically use GetFirstValueByName rather than GetAt because the order of items in a query string usually isn't important, whereas the parameter name is the important identifier of the parts of a query. Or, if you're not sure what names exist in the query string, you might enumerate over the complete WwwFormUrlDecoder collection.

The Uri.QueryParsed property returns a complete WwwFormUrlDecoder based on a Uri instance. So if you're using Visual C++ component extensions (C++/CX) or JavaScript code, and you already have a Uri instance, you won't need to construct a new WwwFormUrlDecoder object, the Uri instance already has one. You might construct a WwwFormUrlDecoder if you have a string representing a URL or its query string component from other sources, such as from a Windows.Web.Http API.

Note

This collection is a vector rather than a map in case the original order has any meaning to an implementation, and also because it's legal for the same name to appear in the query string twice, whereas it's not legal for maps to have duplicate keys.

Collection member lists

For .NET usage, WwwFormUrlDecoder has the projected APIs of a generic IReadOnlyList with a IWwwFormUrlDecoderEntry constraint. The APIs that are available for each language are indicated in the member lists.

For JavaScript, WwwFormUrlDecoder has the members shown in the member lists. In addition, WwwFormUrlDecoder supports a length property, members of Array.prototype, and using an index to access items.

.NET usage

.NET code can't use the Windows.Foundation.Uri class (you use System.Uri instead). But .NET code can and should use WwwFormUrlDecoder. Using WwwFormUrlDecoder is simpler and less error-prone than string-splitting on "&" and "=" characters. That gets complicated because of encoding. To use WwwFormUrlDecoder, call the WwwFormUrlDecoder constructor, passing in the Query value from your System.Uri. This initializes a new WwwFormUrlDecoder object. Then use GetFirstValueByName to find a specific named query string parameter. Or, if you don't know what's going to be in the query string, enumerate over the collection to determine the query string parameters that are available.

Use the IWwwFormUrlDecoderEntry interface for the type of the items in the collection (this is how the items are typed by IndexOf ). Don't use the WwwFormUrlDecoderEntry class, it isn't available for .NET usage.

WwwFormUrlDecoder also has the projected APIs of a generic IReadOnlyList with a IWwwFormUrlDecoderEntry constraint, but these APIs aren't commonly used.

Note

System.Web.HttpUtility.ParseQueryString isn't available for .NET for Windows Runtime app. WwwFormUrlDecoder is the recommended replacement for it.

Enumerating the collection in C# or Microsoft Visual Basic

WwwFormUrlDecoder is enumerable, so you can use language-specific syntax such as foreach in C# to enumerate the items in the collection. The compiler does the type-casting for you and you won't need to cast to IEnumerable<IWwwFormUrlDecoderEntry> explicitly. If you do need to cast explicitly, for example if you want to call GetEnumerator, cast to IEnumerable<T> with an IWwwFormUrlDecoderEntry constraint.

Constructors

WwwFormUrlDecoder(String) WwwFormUrlDecoder(String) WwwFormUrlDecoder(String) WwwFormUrlDecoder(String)

Creates and initializes a new instance of the WwwFormUrlDecoder class.

public : WwwFormUrlDecoder(PlatForm::String query)public WwwFormUrlDecoder(String query)Public Sub New(query As String)// You can use this method in JavaScript.
Parameters
query
PlatForm::String String String String

The URL to parse.

Remarks

The query string must start with a '?' character.

Any '&' character encountered represents a new name-value pair. If there is a '=' character present in the string, the substring to the left of the '=' character is the name and the right substring is the value.

The constructor doesn't do much validation on the string beyond verifying that it isn't null or the wrong type. If your input doesn't correctly represent a query string that starts with '?' and contains name-value pairs separated by '&', the collection contents are empty or invalid, and calls to GetFirstValueByName won't have the expected result.

URL-encoded characters are not decoded, they are simply included in the name-value pairs.

See Also

Properties

Item[Int32] Item[Int32] Item[Int32] Item[Int32]

Gets the element at the specified index in the read-only list.

This member is not implemented in C++T this[int index] { get; }ReadOnly Property Item(index As Integer) As TT this[int index] { get; }
Parameters
index

The zero-based index of the element to get.

Value
T T T T

The element at the specified index in the read-only list.

Size Size Size Size

Gets the number of the name-value pairs in the current URL query string.

public : unsigned int Size { get; }This member is not implemented in C#This member is not implemented in VB.Net// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The number of the name-value pairs.

Remarks

Name-value pairs are represented by IWwwFormUrlDecoderEntry objects.

Methods

First() First() First() First()

Gets an iterator that represents the first name-value pair in the current URL query string.

public : IIterator<IWwwFormUrlDecoderEntry> First()This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.
Returns

GetAt(UInt32) GetAt(UInt32) GetAt(UInt32) GetAt(UInt32)

Gets the name-value pair at the specified index in the current URL query string.

public : IWwwFormUrlDecoderEntry GetAt(unsigned int index)This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.
Parameters
index
unsigned int UInt32 UInt32 UInt32

The index of the name-value pair.

Returns

GetEnumerator() GetEnumerator() GetEnumerator() GetEnumerator()

Returns an enumerator that iterates through the collection.

This member is not implemented in C++IEnumerator<T> GetEnumerator()Function GetEnumerator As IEnumerator(Of T)IEnumerator<T> GetEnumerator()
Returns

An enumerator that can be used to iterate through the collection.

GetFirstValueByName(String) GetFirstValueByName(String) GetFirstValueByName(String) GetFirstValueByName(String)

Gets the first name-value pair that has the specified name, as obtained from the constructing Uniform Resource Identifier (URI) query string.

public : PlatForm::String GetFirstValueByName(PlatForm::String name)public string GetFirstValueByName(String name)Public Function GetFirstValueByName(name As String) As string// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The name of the value to get.

Returns
PlatForm::String string string string

The first value in list order that corresponds with name.

Remarks

This method throws an exception (an error for JavaScript) if the value specified as name doesn't exist in the WwwFormUrlDecoder collection. For .NET code, this is typed as System.ArgumentException. You'll probably want to call GetFirstValueByName within a try-catch block so you have a chance to handle the exception.

What to do with duplicate names in a query string from a GET request is not specified by any Internet standard. A common practice is to process the first value and ignore the subsequent duplicates. The GetFirstValueByName method provides that behavior. It also provides the de-facto "index by string" behavior, which is typically what you want when you're processing a query string. Your app is expecting certain names to be present on the query string, and wants to retrieve the associated value.

GetMany(UInt32, IWwwFormUrlDecoderEntry[]) GetMany(UInt32, IWwwFormUrlDecoderEntry[]) GetMany(UInt32, IWwwFormUrlDecoderEntry[]) GetMany(UInt32, IWwwFormUrlDecoderEntry[])

Gets name-value pairs starting at the specified index in the current URL query string.

public : unsigned int GetMany(unsigned int startIndex, IWwwFormUrlDecoderEntry[] items)This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.
Parameters
startIndex
unsigned int UInt32 UInt32 UInt32

The index to start getting name-value pairs at.

items
IWwwFormUrlDecoderEntry[] IWwwFormUrlDecoderEntry[] IWwwFormUrlDecoderEntry[] IWwwFormUrlDecoderEntry[]

The name-value pairs.

Returns
unsigned int uint uint uint

The number of name-value pairs in items.

IndexOf(IWwwFormUrlDecoderEntry, UInt32) IndexOf(IWwwFormUrlDecoderEntry, UInt32) IndexOf(IWwwFormUrlDecoderEntry, UInt32) IndexOf(IWwwFormUrlDecoderEntry, UInt32)

Gets a value indicating whether the specified IWwwFormUrlDecoderEntry is at the specified index in the current URL query string.

public : PlatForm::Boolean IndexOf(IWwwFormUrlDecoderEntry value, unsigned int index)This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.
Parameters
index
unsigned int UInt32 UInt32 UInt32

The position in value.

Returns
PlatForm::Boolean bool bool bool

true if value is at the position specified by index; otherwise, false.

See Also