--- product: Chilkat product_version: 11.7.0 language: csharp language_label: C# class: Hashtable license: free deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/csHashtableRef.html --- # Chilkat Hashtable — C# — v11.7.0 > Chilkat 11.7.0 · language=csharp · class=Hashtable > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/Hashtable.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/csharp/guide.md`. ## Purpose **Store, look up, remove, enumerate, import, and serialize key/value pairs.** `Chilkat.Hashtable` provides a simple key/value collection for storing string and integer values by key. It can add or replace entries, look up values, test whether keys exist, remove entries, count items, enumerate keys, import URL query parameters, serialize values back to a query string, and save or load the table in XML format. **String and integer values** Store values as strings or integers using straightforward add, replace, and lookup methods. **Fast key lookup** Check whether a key exists and retrieve its value without manually scanning a list or parsing text. **Add, replace, and remove** Maintain a mutable collection by adding new entries, replacing existing values, removing individual keys, or clearing the table. **Enumerate keys** Retrieve the set of keys when application logic needs to loop through the stored entries. **Query string helpers** Import URL query parameters into the table and serialize the table back to a query-string representation. **XML persistence** Save the hashtable to XML or reload it from XML when values need to be persisted or transferred in a simple structured format. **Common pattern:** Use `Hashtable` when application code needs a small mutable key/value table, especially for lookup tables, parsed query parameters, or simple string/integer settings. Add values with `AddStr` or `AddInt`, retrieve them with `LookupStr` or `LookupInt`, and use XML or query-string methods when the table needs to be saved, loaded, or converted. For an extended overview, see [Hashtable Class Overview](https://www.chilkatsoft.com/hashtable_class_overview.asp). ## Object creation, unlocking and error handling **Object Creation** ```csharp Chilkat.Hashtable obj = new Chilkat.Hashtable(); ``` Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in C#. Minimal complete program: ```csharp // Required once per process. Any string unlocks a 30-day trial; use your purchased code in production. Chilkat.Global glob = new Chilkat.Global(); if (!glob.UnlockBundle("Anything for 30-day trial")) { Console.WriteLine(glob.LastErrorText); return; } Chilkat.Hashtable hashtable = new Chilkat.Hashtable(); bool success = hashtable.AddQueryParams(""); if (!success) { Console.WriteLine(hashtable.LastErrorText); // full diagnostic of what went wrong return; } ``` How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called. ## Members common to every Chilkat class Documented once per language in `common-members.md`; listed here so this page is self-contained. | Property | Signature | Access | Meaning | |---|---|---|---| | `DebugLogFilePath` | `public string DebugLogFilePath {get; set; }` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. | | `LastErrorHtml` | `public string LastErrorHtml {get; }` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `public string LastErrorText {get; }` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `public string LastErrorXml {get; }` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `public bool LastMethodSuccess {get; set; }` | read/write | Indicates the success or failure of the most recent method call: `true` means success, `false` means failure. | | `VerboseLogging` | `public bool VerboseLogging {get; set; }` | read/write | If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `public string Version {get; }` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `Count` | property, read-only | `public int Count {get; }` | | `AddFromXmlSb` | method | `public bool AddFromXmlSb(StringBuilder sbXml);` | | `AddInt` | method | `public bool AddInt(string key, int value);` | | `AddQueryParams` | method | `public bool AddQueryParams(string queryParams);` | | `AddStr` | method | `public bool AddStr(string key, string value);` | | `Clear` | method | `public void Clear();` | | `ClearWithNewCapacity` | method | `public bool ClearWithNewCapacity(int capacity);` | | `Contains` | method | `public bool Contains(string key);` | | `ContainsIntKey` | method | `public bool ContainsIntKey(int key);` | | `GetKeys` | method | `public bool GetKeys(StringTable strTable);` | | `LookupInt` | method | `public int LookupInt(string key);` | | `LookupStr` | method | `public string LookupStr(string key);` | | `Remove` | method | `public bool Remove(string key);` | | `ToQueryString` | method | `public string ToQueryString();` | | `ToXmlSb` | method | `public bool ToXmlSb(StringBuilder sbXml);` | ## Properties ### Hashtable.Count `Chilkat 11.7.0 · csharp · Hashtable · Count · property · read-only · since 9.5.0.97` ```csharp public int Count {get; } ``` The number of entries currently stored in the hashtable. Each key contributes one entry regardless of whether its value is a string or an integer. Adding a new key increases `Count`; replacing the value of an existing key does not. Removing an entry decreases it, and `Clear` resets it to `0`. ## Methods ### Hashtable.AddFromXmlSb `Chilkat 11.7.0 · csharp · Hashtable · AddFromXmlSb · method · since 9.5.0.64` ```csharp public bool AddFromXmlSb(StringBuilder sbXml); ``` Reads hashtable XML previously produced by `ToXmlSb` from the `StringBuilder` passed in `sbXml` and adds the entries to this table. The operation merges with the existing table: keys not present in the XML remain, and an imported entry replaces the current value for the same key. Call `Clear` first when the XML should completely replace the current contents. Returns `true` when the XML is parsed and imported successfully; otherwise returns `false`. Returns true for success, false for failure. ### Hashtable.AddInt `Chilkat 11.7.0 · csharp · Hashtable · AddInt · method · since 9.5.0.51` ```csharp public bool AddInt(string key, int value); ``` Adds an entry whose string key is `key` and whose value is the integer `value`. If the key already exists, its previous value is replaced. Returns `true` when the entry is added or replaced. Returns `false` if the operation cannot be completed, such as because memory could not be allocated. **One entry per key:** Adding the same key again replaces the existing value; it does not create a second entry. Replacing a value does not increase `Count`. Use `LookupInt` to retrieve an integer value. Returns true for success, false for failure. ### Hashtable.AddQueryParams `Chilkat 11.7.0 · csharp · Hashtable · AddQueryParams · method · since 9.5.0.62` ```csharp public bool AddQueryParams(string queryParams); ``` Parses URL query parameters from `queryParams` and adds them to the hashtable as string entries. Pass the query component in the following form: ``` field1=value1&field2=value2&field3=value3 ``` Each value is expected to be URL encoded and is URL decoded before being stored. If an imported key already exists, its previous value is replaced. Returns `true` on success and `false` if the query parameters cannot be imported. **Repeated parameter names:** A hashtable stores one value per key. It cannot preserve a query string containing several independent values with the same field name. Use a list-oriented parser when repeated names must remain distinct. Returns true for success, false for failure. ### Hashtable.AddStr `Chilkat 11.7.0 · csharp · Hashtable · AddStr · method · since 9.5.0.51` ```csharp public bool AddStr(string key, string value); ``` Adds an entry whose string key is `key` and whose value is the string `value`. If the key already exists, its previous value is replaced. Returns `true` when the entry is added or replaced. Returns `false` if the operation cannot be completed, such as because memory could not be allocated. **One entry per key:** Adding the same key again replaces the existing value; it does not create a second entry. Replacing a value does not increase `Count`. Use `LookupStr` to retrieve a string value. Returns true for success, false for failure. ### Hashtable.Clear `Chilkat 11.7.0 · csharp · Hashtable · Clear · method · since 9.5.0.51` ```csharp public void Clear(); ``` Removes every entry from the hashtable. After this call, `Count` is `0`. The current hash-table capacity is retained. To clear the entries and also select a different bucket capacity, call `ClearWithNewCapacity`. ### Hashtable.ClearWithNewCapacity `Chilkat 11.7.0 · csharp · Hashtable · ClearWithNewCapacity · method · since 9.5.0.51` ```csharp public bool ClearWithNewCapacity(int capacity); ``` Removes every entry and reinitializes the hashtable with `capacity` buckets. The initial default capacity of a new `Hashtable` object is `521`. Returns `true` on success and `false` if the table cannot be reinitialized. | Term | Meaning | | :--- | :--- | | `Count` | The number of stored entries. | | Capacity | The number of hash buckets, not a maximum entry count. | **Performance note:** More buckets can reduce collisions for a large table, but use more memory. Choosing roughly twice the expected number of entries and using a prime number are tuning guidelines, not correctness requirements. Returns true for success, false for failure. ### Hashtable.Contains `Chilkat 11.7.0 · csharp · Hashtable · Contains · method · since 9.5.0.51` ```csharp public bool Contains(string key); ``` Returns `true` if the hashtable contains the string key `key`; otherwise returns `false`. The result tests key existence regardless of the value stored for that key. **Useful before lookup:** Call `Contains` when a lookup result could be ambiguous. For example, `LookupInt` returns `0` both for a missing key and for an entry whose value is actually zero. ### Hashtable.ContainsIntKey `Chilkat 11.7.0 · csharp · Hashtable · ContainsIntKey · method · since 9.5.0.64` ```csharp public bool ContainsIntKey(int key); ``` Returns `true` if the hashtable contains the integer key `key`; otherwise returns `false`. **Key type:** This method accepts an integer key. It is distinct from `Contains`, which tests for a string key, and from `AddInt`, whose key is a string and whose value is an integer. ### Hashtable.GetKeys `Chilkat 11.7.0 · csharp · Hashtable · GetKeys · method · since 9.5.0.62` ```csharp public bool GetKeys(StringTable strTable); ``` Appends all hashtable key strings to the `StringTable` passed in `strTable`. Existing strings already contained in `strTable` are not cleared. Returns `true` on success and `false` on failure. **Enumeration order:** Hashtable keys may be returned in any order. Do not depend on insertion order or sorted order. Clear the destination `StringTable` first when it should contain only the current hashtable keys. Returns true for success, false for failure. ### Hashtable.LookupInt `Chilkat 11.7.0 · csharp · Hashtable · LookupInt · method · since 9.5.0.51` ```csharp public int LookupInt(string key); ``` Returns the integer value associated with the string key `key`. This method is intended for entries stored with `AddInt`. If the key does not exist, the return value is `0`. **Missing key versus zero:** Because `0` is also a valid stored value, call `Contains` first when the application must distinguish a missing key from an entry containing zero. ### Hashtable.LookupStr `Chilkat 11.7.0 · csharp · Hashtable · LookupStr · method · since 9.5.0.51` ```csharp public string LookupStr(string key); ``` Returns the string value associated with the string key `key`. This method is intended for entries stored as strings, including entries added by `AddStr` or `AddQueryParams`. **Check lookup success:** The representation of a failed string-returning call varies by programming language and may be `null`, `Nothing`, or an empty string. An empty string may also be a legitimate value. Use `Contains` or `LastMethodSuccess` when the distinction matters. Returns `null` on failure ### Hashtable.Remove `Chilkat 11.7.0 · csharp · Hashtable · Remove · method · since 9.5.0.51` ```csharp public bool Remove(string key); ``` Removes the entry whose string key is `key`. - Returns `true` if the key existed and the entry was removed. - Returns `false` if the key was not present. A `false` result caused by an absent key is a normal lookup outcome, not an indication that the hashtable was damaged. Removing an existing entry decreases `Count` by one. ### Hashtable.ToQueryString `Chilkat 11.7.0 · csharp · Hashtable · ToQueryString · method · since 9.5.0.92` ```csharp public string ToQueryString(); ``` Serializes the hashtable as a URL query string in the following form: ``` key1=value1&key2=value2&key3=value3 ``` Each value is URL encoded. The returned string does not include a leading `?`. **Important limitations:** Key order is not defined, and a hashtable contains only one value per key. Therefore the output is not suitable when parameter order is significant or repeated field names must be preserved. In language bindings where string-return failure is ambiguous, check `LastMethodSuccess`. Returns `null` on failure ### Hashtable.ToXmlSb `Chilkat 11.7.0 · csharp · Hashtable · ToXmlSb · method · since 9.5.0.64` ```csharp public bool ToXmlSb(StringBuilder sbXml); ``` Serializes the current hashtable to Chilkat's hashtable XML format and appends the XML to the `StringBuilder` passed in `sbXml`. Existing content in the `StringBuilder` is preserved. Returns `true` on success and `false` on failure. The generated XML can be loaded by `AddFromXmlSb`. ``` <hashtable> <e><k>key</k><v>value</v></e> </hashtable> ``` **Ordering:** Because hashtable enumeration order is not defined, do not rely on entries appearing in insertion order or use the serialized text as a canonical, byte-for-byte representation. Returns true for success, false for failure. ## Related classes [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/csharp/classes/StringBuilder.md), [`StringTable`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/csharp/classes/StringTable.md)