WwwFormUrlDecoder WwwFormUrlDecoder WwwFormUrlDecoder WwwFormUrlDecoder Class

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

Syntax

Declaration

public sealed class WwwFormUrlDecoderpublic sealed class WwwFormUrlDecoderPublic NotInheritable Class WwwFormUrlDecoderpublic sealed class WwwFormUrlDecoder

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(String) to find a specific named query string parameter. All languages can use this method. You'd typically use GetFirstValueByName(String) rather than GetAt(UInt32) 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 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 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 @Windows.Foundation.WwwFormUrlDecoder.#ctor(System.String) constructor, passing in the Query value from your System.Uri. This initializes a new WwwFormUrlDecoder object. Then use GetFirstValueByName(String) 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(IWwwFormUrlDecoderEntry, UInt32) ). 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 summary

Creates and initializes a new instance of the WwwFormUrlDecoder class.

Properties summary

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

Methods summary

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

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

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

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

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

Constructors

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

    Creates and initializes a new instance of the WwwFormUrlDecoder class.

    public WwwFormUrlDecoder(String query)public New(String query)Public Sub New(query As String)public WwwFormUrlDecoder(String query)

    Parameters

    • query
      System.String
      System.String
      System.String
      System.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(String) won't have the expected result.

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

Properties

  • Size
    Size
    Size
    Size

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

    public uint Size { get; }public uint Size { get; }Public ReadOnly Property Size As uintpublic uint Size { get; }

    Property Value

    • uint
      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()public IIterator<IWwwFormUrlDecoderEntry> First()Public Function First() As IIterator( Of IWwwFormUrlDecoderEntry )public IIterator<IWwwFormUrlDecoderEntry> First()

    Returns

    • The first name-value pair.

  • 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(UInt32 index)public IWwwFormUrlDecoderEntry GetAt(UInt32 index)Public Function GetAt(index As UInt32) As IWwwFormUrlDecoderEntrypublic IWwwFormUrlDecoderEntry GetAt(UInt32 index)

    Parameters

    • index
      System.UInt32
      System.UInt32
      System.UInt32
      System.UInt32

      The index of the name-value pair.

    Returns

  • 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 string GetFirstValueByName(String name)public string GetFirstValueByName(String name)Public Function GetFirstValueByName(name As String) As stringpublic string GetFirstValueByName(String name)

    Parameters

    • name
      System.String
      System.String
      System.String
      System.String

      The name of the value to get.

    Returns

    • 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(String) 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(String) 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 uint GetMany(UInt32 startIndex, IWwwFormUrlDecoderEntry[] items)public uint GetMany(UInt32 startIndex, IWwwFormUrlDecoderEntry[] items)Public Function GetMany(startIndex As UInt32, items As IWwwFormUrlDecoderEntry[]) As uintpublic uint GetMany(UInt32 startIndex, IWwwFormUrlDecoderEntry[] items)

    Parameters

    • startIndex
      System.UInt32
      System.UInt32
      System.UInt32
      System.UInt32

      The index to start getting name-value pairs at.

    • items
      Windows.Foundation.IWwwFormUrlDecoderEntry[]
      Windows.Foundation.IWwwFormUrlDecoderEntry[]
      Windows.Foundation.IWwwFormUrlDecoderEntry[]
      Windows.Foundation.IWwwFormUrlDecoderEntry[]

      The name-value pairs.

    Returns

    • uint
      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 bool IndexOf(IWwwFormUrlDecoderEntry value, UInt32 index)public bool IndexOf(IWwwFormUrlDecoderEntry value, UInt32 index)Public Function IndexOf(value As IWwwFormUrlDecoderEntry, index As UInt32) As boolpublic bool IndexOf(IWwwFormUrlDecoderEntry value, UInt32 index)

    Parameters

    Returns

    • bool
      bool
      bool
      bool

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

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.Foundation.dll