What the Class Is Used For

Use Chilkat.Url when an application needs to break a full URL into its component parts. After calling ParseUrl, the parsed values are available through read-only properties such as Host, Path, Query, Port, and Ssl.

Parse URLs Call ParseUrl with a full URL to populate all URL component properties.

Inspect Host Details Read the host name or IP address and determine whether it is DNS, IPv4, or IPv6.

Read Path and Query Access the path alone, the query string alone, or the path including query parameters.

Detect SSL/TLS Use Ssl and Port to identify HTTPS-style URLs and their port.

Typical Workflow

Create a Url object.
Call ParseUrl with the full URL string.
Check the boolean return value.
Read properties such as Host, HostType, Path, Query, Frag, Port, and Ssl.
If parsing fails or produces unexpected results, inspect LastErrorText.

Parse first: The component properties reflect the most recently parsed URL. Call ParseUrl before reading them.

Example URL Breakdown

A URL can contain credentials, host, port, path, query parameters, and a fragment:

https://user:password@example.com:8443/docs/index.html?x=1&y=2#section1

Property	Value from Example	Meaning
Login	user	Login name from the user-info portion of the URL.
Password	password	Password from the user-info portion of the URL.
Host	example.com	DNS host name or IP address.
HostType	dns	Identifies whether the host is DNS, IPv4, or IPv6.
Port	8443	Explicit port number from the URL.
Path	/docs/index.html	Path portion, excluding query and fragment.
Query	x=1&y=2	Query string, excluding the question mark and fragment.
PathWithQueryParams	/docs/index.html?x=1&y=2	Path plus query parameters, excluding the fragment.
Frag	section1	Fragment text after #, excluding the marker.
Ssl	true	True because the URL begins with https://.

Core Concepts

Concept	Meaning	Important Members
URL Parsing	The process of breaking a full URL into its component parts.	ParseUrl
Host	The DNS name, IPv4 address, or IPv6 address in the URL.	Host, HostType
User Info	Optional login and password embedded in the URL before the host.	Login, Password
Path	The resource path, excluding query string and fragment.	Path
Query	The query string after ?, excluding the fragment.	Query, PathWithQueryParams
Fragment	The part after #, excluding the marker.	Frag
SSL/TLS	Whether the URL indicates HTTPS-style SSL/TLS usage.	Ssl, Port

Method

Method	Purpose	Result
ParseUrl	Parses a full URL string.	Returns true for success and false for failure. After successful parsing, the URL parts are available in the class properties.

Properties

Property	Contains	Example / Notes
Host	DNS host name or IP address.	For http://www.contoso.com:8080/, the host is www.contoso.com.
HostType	Type of host in the URL.	Possible values are dns, ipv4, and ipv6.
Port	Port number.	Explicit ports are returned when present. Default ports are returned when the URL omits the port.
Ssl	Whether the URL indicates SSL/TLS.	True for URLs beginning with https://.
Path	Path and parameters, excluding query and fragment.	For /gp/product/1476752842/ref=s9_psimh..., the path excludes the ? query string and # fragment.
PathWithQueryParams	Path including query parameters, excluding fragment.	Useful when building an HTTP request target path that includes the query string.
Query	Query string, excluding fragment.	Does not include the leading ?.
Frag	Fragment text.	Does not include the leading #.
Login	Login name from URL user-info.	For http://user:password@www.contoso.com/index.htm, the login is user.
Password	Password from URL user-info.	For http://user:password@www.contoso.com/index.htm, the password is password.
LastErrorText	Diagnostic information for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Host Types

HostType	Meaning	Example Host
dns	Domain Name System style host name.	www.contoso.com
ipv4	IPv4 address.	192.168.1.124
ipv6	IPv6 address.	2001:db8::1

Path, Query, and Fragment

Part	Property	Includes	Excludes
Path	Path	Path and path parameters.	Query string and fragment.
Path + query	PathWithQueryParams	Path and query parameters.	Fragment.
Query	Query	Query text after ?.	Leading ? and fragment.
Fragment	Frag	Fragment text after #.	Leading #.

Port and SSL/TLS Behavior

URL Pattern	Port	SSL/TLS
http://www.contoso.com:8080/	8080	false
https://www.amazon.com/	443	true
https://192.168.1.124/test.html	Default port returned by the parser when no explicit port is present.	true

Port note: If a URL contains an explicit port, that port is returned. If no port is present, the parser returns the default port associated with the parsed URL.

Method and Property Summary

Category	Members	Purpose
Parse	ParseUrl	Parse a full URL and populate the component properties.
Host	Host, HostType	Retrieve the host name/IP address and identify whether it is DNS, IPv4, or IPv6.
User info	Login, Password	Retrieve login and password values embedded in the URL.
Path and query	Path, PathWithQueryParams, Query	Retrieve path, path with query parameters, or query string alone.
Fragment	Frag	Retrieve the URL fragment without the leading #.
Port and TLS	Port, Ssl	Determine the parsed port and whether the URL indicates SSL/TLS.
Diagnostics	LastErrorText	Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Parsing fails	ParseUrl, LastErrorText	Confirm the input is a full URL string and inspect LastErrorText for diagnostic details.
Properties are empty or unexpected	ParseUrl	Ensure ParseUrl was called successfully before reading component properties.
Need path for an HTTP request target	PathWithQueryParams	Use this property when the query string should be included with the path.
Need query parameters only	Query	Use this property to get the query string without the leading ? and without the fragment.
Need to determine host style	HostType	Check whether the host was parsed as dns, ipv4, or ipv6.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected parsing behavior.

Common Pitfalls

Pitfall	Better Approach
Reading properties before calling ParseUrl.	Call ParseUrl first and check its return value.
Expecting Query to include the leading question mark.	Query returns the query text without ?.
Expecting Frag to include the leading hash marker.	Frag returns the fragment text without #.
Using Path when the query string is also needed.	Use PathWithQueryParams when the path and query should remain together.
Assuming every URL contains login and password values.	Read Login and Password only when the URL includes user-info.
Ignoring parsing diagnostics.	Check LastErrorText when parsing fails or returns unexpected component values.

Best Practices

Recommendation	Reason
Check the return value of ParseUrl.	The properties are meaningful only after a successful parse.
Use PathWithQueryParams for HTTP request paths.	Many HTTP request targets need the path and query string together.
Use HostType when IP address handling matters.	It distinguishes DNS names from IPv4 and IPv6 addresses.
Avoid logging embedded URL passwords.	Password may contain sensitive data when the URL includes user-info.
Use Ssl and Port together.	They help determine whether the URL indicates SSL/TLS and which port should be used.
Check LastErrorText after failures.	It provides useful diagnostic detail for URL parsing problems.

Summary

Chilkat.Url is a simple URL parser that separates a full URL into useful read-only properties. It provides the host, host type, login, password, path, path with query parameters, query string, fragment, port, and SSL/TLS indication after a successful call to ParseUrl.

The most important practical guidance is to call ParseUrl first, check its return value, use PathWithQueryParams when the query string should stay attached to the path, remember that Query excludes ? and Frag excludes #, and inspect LastErrorText whenever parsing fails or results are unexpected.

Chilkat.Url Class Overview