Codeunit 3061 Uri Builder

System Application, System.Utilities

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&amp;john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;$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&amp;john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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&amp;john=doe" and the new flag is "contoso=42", the result could be "https://microsoft.com?john=doe&amp;foo=bar&amp;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.";}