# Uri

> Parse a URL into its parts with the C#-faithful `new Uri(url)` handle. Construct it from a URL string, then read `.Scheme`, `.Host`, `.Port`, `.AbsolutePath`, `.PathAndQuery`, `.Query`, and `.Fragment`. Pure — no capability needed. Pairs with the HTTP surface (parse a webhook or redirect URL).

<!-- id: stdlib-uri · area: stdlib · stability: stable · html: https://osysharp.com/reference/stdlib/uri/ -->

## Summary        {#summary}
**`Uri`** is the parsed-URL handle, spelled exactly as in C#. Construct it from a URL string and read its parts:

```osy syntax
var u = new Uri("https://api.example.com:8443/v1/users?active=true#top");
u.Scheme;         // "https"
u.Host;           // "api.example.com"
u.Port;           // 8443
u.AbsolutePath;   // "/v1/users"
u.PathAndQuery;   // "/v1/users?active=true"
u.Query;          // "?active=true"
u.Fragment;       // "#top"
```

It is **pure** — no capability, no `using` required. `Uri` is also where the URL-escaping helpers live
([Encoding — Base64, URL, HTML](https://osysharp.com/reference/stdlib/encoding/) — `Uri.EscapeDataString`), exactly as C#'s `System.Uri` carries both.

## Signature      {#signature}
```osy syntax
Uri     new Uri(string url)      // parse an ABSOLUTE URL

string  uri.Scheme               // "https"
string  uri.Host                 // "api.example.com"
int     uri.Port                 // 8443 (or the scheme default: 443 for https, 80 for http)
string  uri.AbsolutePath         // "/v1/users"
string  uri.PathAndQuery         // "/v1/users?active=true"
string  uri.Query                // "?active=true" (empty when there is none)
string  uri.Fragment             // "#top" (empty when there is none)
```

## Description    {#description}
`new Uri(url)` parses an **absolute** URL once and exposes its components as instance members — the same shape as C#'s
`System.Uri`. When the URL omits the port, `.Port` is the scheme's default (443 for `https`, 80 for `http`). `.Query`
and `.Fragment` include their leading `?` / `#`, and are empty strings when absent.

An **invalid** or **relative** URL throws — `new Uri` parses an absolute URI, faithful to C#. Validate untrusted input
first (e.g. with [Regex](https://osysharp.com/reference/stdlib/regex/)) if a throw is not what you want.

## Examples       {#examples}

Route on the host of a webhook URL, parsing an [Http.*](https://osysharp.com/reference/http/facade/) target:

```osy title="check the host before trusting a webhook URL" test app=stdlib-uri
bool IsTrustedHost(string webhookUrl) {
  var u = new Uri(webhookUrl);
  return u.Scheme == "https" && Text.EndsWith(u.Host, ".example.com");
}
```

Build a URL with an escaped query value ([Encoding — Base64, URL, HTML](https://osysharp.com/reference/stdlib/encoding/)) and read it back:

```osy title="build a URL with an escaped query value" test app=stdlib-uri
Uri Search(string term) {
  return new Uri("https://api.example.com/search?q=" + Uri.EscapeDataString(term));
}
```

## See also       {#see-also}
- [Encoding — Base64, URL, HTML](https://osysharp.com/reference/stdlib/encoding/) — `Uri.EscapeDataString` / `UnescapeDataString` for building the URL you parse
- [Http.*](https://osysharp.com/reference/http/facade/) — the outbound HTTP surface whose URLs this parses
- [Regex](https://osysharp.com/reference/stdlib/regex/) — validate a URL string before parsing untrusted input