{"title":"Dictionary data type","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/methods-auto/dictionary/dictionary-data-type/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/dictionary/dictionary-data-type, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/dictionary/dictionary-data-type","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Represents an unordered collection of keys and values.","date":"2026-10-01","meta":{"topic":"reference"},"outline":[{"level":2,"title":"Instance methods","slug":"instance-methods","at":180,"chars":1069},{"level":2,"title":"Remarks","slug":"remarks","at":1249,"chars":2388}],"text":"> Version: _Available or changed with runtime version 1.0._\nRepresents an unordered collection of keys and values. The Dictionary data type is optimized for fast lookup of values.\n## Instance methods\nThe following methods are available on instances of the Dictionary data type.\nMethod name|Description\nAdd(TKey, TValue)<dictionary-add-method>|Adds the specified key and value to the dictionary.\nContainsKey(TKey)<dictionary-containskey-method>|Determines whether the Dictionary contains the specified key.\ndictionary-count-method|Gets the number of key/value pairs contained in the Dictionary.\nGet(TKey, var TValue)<dictionary-get-tkey-tvalue-method>|Gets the value associated with the specified key.\ndictionary-get-tkey-method|Gets the value associated with the specified key.\ndictionary-keys-method|Gets a collection containing the keys in the Dictionary.\nRemove(TKey)<dictionary-remove-method>|Removes the value with the specified key from the Dictionary.\ndictionary-set-tkey-tvalue-method|Sets the value associated with the specified key.\nSet(TKey, TValue, var TValue)<dictionary-set-tkey-tvalue-tvalue-method>|Sets the value associated with the specified key.\ndictionary-values-method|Gets a collection containing the values in the Dictionary.\n## Remarks\nEach addition to the dictionary consists of a value, and its associated key. Every key in a Dictionary must be unique. A key cannot be null, but a value can be, only when the value type is a reference type.\nA Dictionary is a reference type, so assigning an instance of a dictionary to another variable or passing as a method parameter by value (for example without var), creates a second variable that reads/writes the same dictionary. It does not create a new dictionary.\nTo create a new dictionary that contains the same values as the original dictionary, you can do the following to perform a shallow copy:\n```al\ntrigger OnRun()\n    var\n        dict1: Dictionary of [Integer, Integer];\n        dict2: Dictionary of [Integer, Integer];\n        dictionaryKey: Integer;\n    begin\n        // ...\n        foreach dictionaryKey in dict1.Keys() do\n            dict2.Add(dictionaryKey, dict1.Get(dictionaryKey));\n    end;\n```\nThe Dictionary data type does not support holding instantiated records. For this purpose, use temporary tables.\n> WARNING\n> Previously in C/AL, one would have typically used an in-memory temporary table to create a key-value data structure, as shown in the code below. In AL you use the Dictionary Data Type instead.\n```\n> IF KeyCacheRec.Get(‘Some Value’)​ THEN​\n>     Complete data stack execution;\n> ```\n\n## Example\n\nIn the following example, the variable `counter` represents the Dictionary data type to store a value representing the number of occurrences for each character in the `customerName`. Using the `Get` method, you get the number of occurrences for the character at position `i`. If `i` returns **false**, it means there is no value associated with that character, so you add the value 1. If `i` returns **true**, it means the value already exists, so you add `c + 1` to the value. The `Add` method adds the {key:value} pair to the Dictionary.\n\n```al\nprocedure CountCharactersInCustomerName(customerName: Text; counter: Dictionary of [Char, Integer])\nvar\n    i : Integer;\n    c : Integer;\nbegin\n    for i := 1 to StrLen(customerName) do\n        if counter.Get(customerName[i], c) then\n            counter.Set(customerName[i], c + 1)\n        else\n            counter.Add(customerName[i], 1);\nend;\n\n```\n## Related information\nGet Started with AL<../../devenv-get-started>\nDeveloping Extensions<../../devenv-dev-overview>\n../list/list-data-type"}