Deprecate an ExecuteMetadataQueryAsync() method (#699)

Box.V2/Managers/BoxMetadataManager.cs

@@ -328,6 +328,7 @@ public async Task<BoxEnterpriseMetadataTemplateCollection<BoxMetadataTemplate>>
         /// <param name="marker">The marker to use for requesting the next page</param>
         /// <param name="autoPaginate">Whether or not to auto-paginate to fetch all items; defaults to false.</param>
         /// <returns>A collection of items and their associated metadata</returns>
+        [Obsolete("This method is deprecated in favor of ExecuteMetadataQueryAsync() that has a fields parameter. The API will eventually not support this method.")]
         public async Task<BoxCollectionMarkerBased<BoxMetadataQueryItem>> ExecuteMetadataQueryAsync(string from, string ancestorFolderId, string query = null, Dictionary<string, object> queryParameters = null, string indexName = null, List<BoxMetadataQueryOrderBy> orderBy = null, int limit = 100, string marker = null, bool autoPaginate = false)
         {
             from.ThrowIfNullOrWhiteSpace("from");

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## Next Release
+- Deprecate one of the overloaded `ExecuteMetadataQueryAsync()` methods
+
 ## 3.24.0 [2020-07-21]
 - Add path parameter sanitization
 - Add support for the classification field for Files and Folders

docs/metadata.md

@@ -469,21 +469,7 @@ await client.MetadataManager.DeleteFolderMetadataAsync("11111", "enterprise", "m
 
 Execute Metadata Query
 ------------------------
-There are two types of methods for executing a metadata query, methods without the fields parameter and with it. The methods without the fields parameters return data that is a `BoxMetadataQueryItem`. The methods with the fields parameters return a `BoxItem` object. Examples of these two types are shown below.
-
-The `MetadataManager.ExecuteMetadataQueryAsync(string from, string ancestorFolderId, string query = null, Dictionary<string, object> queryParameters, string indexName, List<BoxMetadataQueryOrderBy> orderBy, int limit, string marker, bool autoPaginate)` method queries files and folders based on their metadata.
-```c#
-var queryParams = new Dictionary<string, object>();
-queryParams.Add("arg", 100);
-List<BoxMetadataQueryOrderBy> orderByList = new List<BoxMetadataQueryOrderBy>();
-var orderBy = new BoxMetadataQueryOrderBy()
-{
-    FieldKey = "amount",
-    Direction = BoxSortDirection.ASC
-};
-orderByList.Add(orderBy);
-BoxCollectionMarkerBased<BoxMetadataQueryItem> items = await _metadataManager.ExecuteMetadataQueryAsync(from: "enterprise_123456.someTemplate", query: "amount >= :arg", queryParameters: queryParams, ancestorFolderId: "5555", indexName: "amountAsc", orderBy: orderByList, autoPaginate: true);
-```
+There are two types of methods for executing a metadata query, methods without the fields parameter and with it. The method with the fields parameters returns a `BoxItem` object. The method without the fields parameters returns data that is a `BoxMetadataQueryItem` and is **deprecated**. The API will eventually not support this method and the other method should be used instead. Examples of these two types are shown below.
 
 The `MetadataManager.ExecuteMetadataQueryAsync(string from, string ancestorFolderId, IEnumerable<string> fields, string query, Dictionary<string, object> queryParameters, string indexName, List<BoxMetadataQueryOrderBy> orderBy, int limit, string marker, bool autoPaginate)` method queries files and folders based on their metadata and allows for fields to be passed in. A returned `BoxItem` must be cast to a `BoxFile` or `BoxFolder` to get its metadata.
 ```c#
@@ -493,13 +479,29 @@ List<string> fields = new List<string>();
 fields.Add("id");
 fields.Add("name");
 fields.Add("sha1");
-fields.Add("metadata.enterprise_240748.catalogImages.catalogImages");
+fields.Add("metadata.enterprise_240748.catalogImages.photographer");
 BoxCollectionMarkerBased<BoxItem> items = await _metadataManager.ExecuteMetadataQueryAsync(from: "enterprise_67890.catalogImages", query: "photographer = :arg", fields: fields, queryParameters: queryParams, ancestorFolderId: "0", autoPaginate: true);
 BoxFile file = (BoxFile) items.Entries[0];
 BoxFolder folder = (BoxFolder) items.Entries[1];
 string metadataFile = file.Metadata["enterprise_240748"]["catalogImages"]["photographer"].Value;
 string metadataFolder = folder.Metadata["enterprise_240748"]["catalogImages"]["photographer"].Value;
 ```
 
+**Deprecated**
+
+The `MetadataManager.ExecuteMetadataQueryAsync(string from, string ancestorFolderId, string query = null, Dictionary<string, object> queryParameters, string indexName, List<BoxMetadataQueryOrderBy> orderBy, int limit, string marker, bool autoPaginate)` method queries files and folders based on their metadata.
+```c#
+var queryParams = new Dictionary<string, object>();
+queryParams.Add("arg", 100);
+List<BoxMetadataQueryOrderBy> orderByList = new List<BoxMetadataQueryOrderBy>();
+var orderBy = new BoxMetadataQueryOrderBy()
+{
+    FieldKey = "amount",
+    Direction = BoxSortDirection.ASC
+};
+orderByList.Add(orderBy);
+BoxCollectionMarkerBased<BoxMetadataQueryItem> items = await _metadataManager.ExecuteMetadataQueryAsync(from: "enterprise_123456.someTemplate", query: "amount >= :arg", queryParameters: queryParams, ancestorFolderId: "5555", indexName: "amountAsc", orderBy: orderByList, autoPaginate: true);
+```
+