Codeunit 3061 Uri Builder
src/System Application/App/URI/src/UriBuilder.Codeunit.al324 lines, Copyright (c) Microsoft Corporation. MIT
// ------------------------------------------------------------------------------------------------// Copyright (c) Microsoft Corporation. All rights reserved.// Licensed under the MIT License. See License.txt in the project root for license information.// ------------------------------------------------------------------------------------------------namespace System.Utilities;/// <summary>/// Provides a custom constructor for uniform resource identifiers (URIs) and modifies URIs for the Uri codeunit./// </summary>/// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder for more information.</remarks>codeunit 3061 "Uri Builder"{ Access = Public; InherentEntitlements = X; InherentPermissions = X; /// <summary> /// Initializes a new instance of the UriBuilder class with the specified URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.-ctor#System_UriBuilder__ctor_System_String_ for more information.</remarks> /// <param name="Uri">A URI string.</param> procedure Init(Uri: Text) begin UriBuilderImpl.Init(Uri); end; /// <summary> /// Sets the scheme name of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.scheme for more information.</remarks> /// <param name="Scheme">A string that represents the scheme name to set.</param> procedure SetScheme(Scheme: Text) begin UriBuilderImpl.SetScheme(Scheme); end; /// <summary> /// Gets the scheme name of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.scheme for more information.</remarks> /// <returns>The scheme name of the URI.</returns> procedure GetScheme(): Text begin exit(UriBuilderImpl.GetScheme()); end; /// <summary> /// Sets the host name of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.host for more information.</remarks> /// <param name="Host">A string that represents the host name to set.</param> procedure SetHost(Host: Text) begin UriBuilderImpl.SetHost(Host); end; /// <summary> /// Gets the host name of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.host for more information.</remarks> /// <returns>The host name of the URI.</returns> procedure GetHost(): Text begin exit(UriBuilderImpl.GetHost()); end; /// <summary> /// Sets the port number of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.port for more information.</remarks> /// <param name="Port">An integer that represents the port number to set.</param> procedure SetPort(Port: Integer) begin UriBuilderImpl.SetPort(Port); end; /// <summary> /// Gets the port number of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.port for more information.</remarks> /// <returns>The port number of the URI.</returns> procedure GetPort(): Integer begin exit(UriBuilderImpl.GetPort()); end; /// <summary> /// Sets the path to the resource referenced by the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.path for more information.</remarks> /// <param name="Path">A string that represents the path to set.</param> procedure SetPath(Path: Text) begin UriBuilderImpl.SetPath(Path); end; /// <summary> /// Gets the path to the resource referenced by the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.path for more information.</remarks> /// <returns>The path to the resource referenced by the URI.</returns> procedure GetPath(): Text begin exit(UriBuilderImpl.GetPath()); end; /// <summary> /// Sets any query information included in the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.query for more information.</remarks> /// <param name="Query">A string that represents the query information to set.</param> procedure SetQuery(Query: Text) begin UriBuilderImpl.SetQuery(Query); end; /// <summary> /// Gets the query information included in the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.query for more information.</remarks> /// <returns>The query information included in the URI.</returns> procedure GetQuery(): Text begin exit(UriBuilderImpl.GetQuery()); end; /// <summary> /// Sets the fragment portion of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.fragment for more information.</remarks> /// <param name="Fragment">A string that represents the fragment portion to set.</param> procedure SetFragment(Fragment: Text) begin UriBuilderImpl.SetFragment(Fragment); end; /// <summary> /// Gets the fragment portion of the URI. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.fragment for more information.</remarks> /// <returns>The fragment portion of the URI.</returns> procedure GetFragment(): Text begin exit(UriBuilderImpl.GetFragment()); end; /// <summary> /// Gets the Uri instance constructed by the specified "Uri Builder" instance. /// </summary> /// <remarks>Visit https://learn.microsoft.com/dotnet/api/system.uribuilder.uri for more information.</remarks> /// <param name="Uri">A Uri that contains the URI constructed by the Uri Builder.</param> procedure GetUri(var Uri: Codeunit Uri) begin UriBuilderImpl.GetUri(Uri); end; /// <summary> /// Adds a flag to the query string of this UriBuilder. In case the same query flag exists already, the action in <paramref name="DuplicateAction"/> is taken. /// </summary> /// <param name="Flag">A flag to add to the query string of this UriBuilder. This value will be encoded before being added to the URI query string. Cannot be empty.</param> /// <param name="DuplicateAction">Specifies which action to take if the flag already exist.</param> /// <error>If the provided <paramref name="Flag"/> is empty.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is <c>"Throw Error"</c> and the flag already exists in the URI.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is not a valid value for the enum.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&foo=bar&contoso".</remarks> procedure AddQueryFlag(Flag: Text; DuplicateAction: Enum "Uri Query Duplicate Behaviour") begin UriBuilderImpl.AddQueryFlag(Flag, DuplicateAction); end; /// <summary> /// Adds a flag to the query string of this UriBuilder. In case the same query flag exists already, only one occurrence is kept. /// </summary> /// <param name="Flag">A flag to add to the query string of this UriBuilder. This value will be encoded before being added to the URI query string. Cannot be empty.</param> /// <error>If the provided <paramref name="Flag"/> is empty.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&foo=bar&contoso".</remarks> /// <remarks>This function will encode OData parameters (and will ensure encoding of the ones added to the <see cref="UriBuilder"/> before). For example "$skip=3" will result in "%24skip=3". Some servers don't support the encoded version. Use <see cref="AddODataQueryParameter"/> in these cases instead.</remarks> procedure AddQueryFlag(Flag: Text) begin UriBuilderImpl.AddQueryFlag(Flag, Enum::"Uri Query Duplicate Behaviour"::"Overwrite All Matching"); end; /// <summary> /// Adds a parameter key-value pair to the query string of this UriBuilder (in the form <c>ParameterKey=ParameterValue</c>). In case the same query key exists already, the action in <paramref name="DuplicateAction"/> is taken. /// </summary> /// <param name="ParameterKey">The key for the new query parameter. This value will be encoded before being added to the URI query string. Cannot be empty.</param> /// <param name="ParameterValue">The value for the new query parameter. This value will be encoded before being added to the URI query string. Can be empty.</param> /// <param name="DuplicateAction">Specifies which action to take if the ParameterKey specified already exist.</param> /// <error>If the provided <paramref name="ParameterKey"/> is empty.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is <c>"Throw Error"</c>.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is not a valid value for the enum.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&foo=bar&contoso=42".</remarks> /// <remarks>This function will encode OData parameters (and will ensure encoding of the ones added to the <see cref="UriBuilder"/> before). For example "$skip=3" will result in "%24skip=3". Some servers don't support the encoded version. Use <see cref="AddODataQueryParameter"/> in these cases instead.</remarks> procedure AddQueryParameter(ParameterKey: Text; ParameterValue: Text; DuplicateAction: Enum "Uri Query Duplicate Behaviour") begin UriBuilderImpl.AddQueryParameter(ParameterKey, ParameterValue, DuplicateAction); end; /// <summary> /// Adds a parameter key-value pair to the query string of this UriBuilder (in the form <c>ParameterKey=ParameterValue</c>). In case the same query key exists already, its value is overwritten. /// </summary> /// <param name="ParameterKey">The key for the new query parameter. This value will be encoded before being added to the URI query string. Cannot be empty.</param> /// <param name="ParameterValue">The value for the new query parameter. This value will be encoded before being added to the URI query string. Can be empty.</param> /// <error>If the provided <paramref name="ParameterKey"/> is empty.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&foo=bar&contoso=42".</remarks> /// <remarks>This function will encode OData parameters (and will ensure encoding of the ones added to the <see cref="UriBuilder"/> before). For example "$skip=3" will result in "%24skip=3". Some servers don't support the encoded version. Use <see cref="AddODataQueryParameter"/> in these cases instead.</remarks> procedure AddQueryParameter(ParameterKey: Text; ParameterValue: Text) begin UriBuilderImpl.AddQueryParameter(ParameterKey, ParameterValue, Enum::"Uri Query Duplicate Behaviour"::"Overwrite All Matching"); end; /// <summary> /// Adds an OData parameter key-value pair to the query string of this UriBuilder (in the form <c>ParameterKey=ParameterValue</c>), preserving the "$" sign in unencoded form. In case the same query key exists already, its value is overwritten. /// </summary> /// <param name="ParameterKey">The key for the new query parameter. This value will be encoded before being added to the URI query string, except for any "$" sign. Cannot be empty.</param> /// <param name="ParameterValue">The value for the new query parameter. This value will be encoded before being added to the URI query string. Can be empty.</param> /// <error>If the provided <paramref name="ParameterKey"/> is empty.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&foo=bar&contoso=42".</remarks> /// <remarks>This function might modify existing query parameters to apply the same encoding rules. For example if the URL is "https://microsoft.com?%24top=1" and the new flag is "$skip=42", the result could be "https://microsoft.com?$skip=42&$top=1".</remarks> procedure AddODataQueryParameter(ParameterKey: Text; ParameterValue: Text) begin UriBuilderImpl.AddODataQueryParameter(ParameterKey, ParameterValue); end; /// <summary> /// Removes a flag from the query string of this UriBuilder. In case the same query flag exists already, the action in <paramref name="DuplicateAction"/> is taken. /// </summary> /// <param name="Flag">A flag to Remove from the query string of this UriBuilder. This value will be encoded before being Removed to the URI query string. Cannot be empty.</param> /// <param name="DuplicateAction">Specifies which action to take if the flag specified already exist.</param> /// <error>If the provided <paramref name="Flag"/> is empty.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is <c>"Throw Error"</c> and the flag does not exist in the URI.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is not a valid value for the enum.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&foo=bar&contoso".</remarks> procedure RemoveQueryFlag(Flag: Text; DuplicateAction: Enum "Uri Query Duplicate Behaviour") begin UriBuilderImpl.AddQueryFlag(Flag, DuplicateAction, true); end; /// <summary> /// Removes a flag from the query string of this UriBuilder. In case the same query flag exists already, only one occurrence is kept. /// </summary> /// <param name="Flag">A flag to Remove from the query string of this UriBuilder. This value will be encoded before being Removed to the URI query string. Cannot be empty.</param> /// <error>If the provided <paramref name="Flag"/> is empty.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&foo=bar&contoso".</remarks> procedure RemoveQueryFlag(Flag: Text) begin UriBuilderImpl.AddQueryFlag(Flag, Enum::"Uri Query Duplicate Behaviour"::"Overwrite All Matching", true); end; /// <summary> /// Removes a parameter key-value pair from the query string of this UriBuilder (in the form <c>ParameterKey=ParameterValue</c>). In case the same query key exists already, the action in <paramref name="DuplicateAction"/> is taken. /// </summary> /// <param name="ParameterKey">The key for the new query parameter. This value will be encoded before being Removed to the URI query string. Cannot be empty.</param> /// <param name="ParameterValue">The value for the new query parameter. This value will be encoded before being Removed to the URI query string. Can be empty.</param> /// <param name="DuplicateAction">Specifies which action to take if the ParameterKey specified already exist.</param> /// <error>If the provided <paramref name="ParameterKey"/> is empty.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is <c>"Throw Error"</c>.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is not a valid value for the enum.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&foo=bar&contoso=42".</remarks> procedure RemoveQueryParameter(ParameterKey: Text; ParameterValue: Text; DuplicateAction: Enum "Uri Query Duplicate Behaviour") begin UriBuilderImpl.RemoveQueryParameter(ParameterKey, ParameterValue, DuplicateAction); end; /// <summary> /// Removes a parameter key-value pair from the query string of this UriBuilder (in the form <c>ParameterKey=ParameterValue</c>). In case the same query key exists already, its value is overwritten. /// </summary> /// <param name="ParameterKey">The key for the new query parameter. This value will be encoded before being Removed to the URI query string. Cannot be empty.</param> /// <param name="ParameterValue">The value for the new query parameter. This value will be encoded before being Removed to the URI query string. Can be empty.</param> /// <error>If the provided <paramref name="ParameterKey"/> is empty.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&foo=bar&contoso=42".</remarks> procedure RemoveQueryParameter(ParameterKey: Text; ParameterValue: Text) begin UriBuilderImpl.RemoveQueryParameter(ParameterKey, ParameterValue, Enum::"Uri Query Duplicate Behaviour"::"Overwrite All Matching"); end; /// <summary> /// Removes a parameter key-value pair from the query string of this UriBuilder (in the form <c>ParameterKey=ParameterValue</c>). In case the same query key exists already, the action in <paramref name="DuplicateAction"/> is taken. /// </summary> /// <param name="ParameterKey">The key for the new query parameter. This value will be encoded before being Removed to the URI query string. Cannot be empty.</param> /// <param name="DuplicateAction">Specifies which action to take if the ParameterKey specified already exist.</param> /// <error>If the provided <paramref name="ParameterKey"/> is empty.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is <c>"Throw Error"</c>.</error> /// <error>If the provided <paramref name="DuplicateAction"/> is not a valid value for the enum.</error> /// <remarks>This function could alter the order of the existing query string parts. For example, if the previous URL was "https://microsoft.com?foo=bar&john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&foo=bar&contoso=42".</remarks> procedure RemoveQueryParameters() begin UriBuilderImpl.RemoveQueryParameters(); end; /// <summary> /// Gets the flags in the query string of this UriBuilder. /// </summary> /// <returns>A list of flags in the query string of this UriBuilder.</returns> procedure GetQueryFlags(): List of [Text] begin exit(UriBuilderImpl.GetQueryFlags()); end; /// <summary> /// Gets the parameters in the query string of this UriBuilder. /// </summary> /// <returns>A dictionary of parameters in the query string of this UriBuilder.</returns> procedure GetQueryParameters(): Dictionary of [Text, List of [Text]] begin exit(UriBuilderImpl.GetQueryParameters()); end; /// <summary> /// Gets the value of the specified query parameter. /// </summary> /// <param name="ParameterKey">The key of the query parameter to get the value of.</param> /// <returns>The value of the specified query parameter.</returns> procedure GetQueryParameter(ParameterKey: Text): List of [Text] begin exit(UriBuilderImpl.GetQueryParameter(ParameterKey)); end; var UriBuilderImpl: Codeunit "Uri Builder Impl.";}