/// <summary>
 /// Create an instance of the <see cref="PhotoSearchOptions"/> for a given user ID and tag list,
 /// with the selected tag mode, and containing the selected text.
 /// </summary>
 /// <param name="userId">The ID of the User to search for.</param>
 /// <param name="tags">The tags (comma delimited) to search for.</param>
 /// <param name="tagMode">The <see cref="TagMode"/> to use to search.</param>
 /// <param name="text">The text to search for in photo title and descriptions.</param>
 public PhotoSearchOptions(string userId, string tags, TagMode tagMode, string text)
 {
     UserId = userId;
     Tags = tags;
     TagMode = tagMode;
     Text = text;
 }

 public PhotoSearchOptions(string userId, string tags, TagMode tagMode, string text)
 {
     this.UserId = userId;
       this.Tags = tags;
       this.TagMode = tagMode;
       this.Text = text;
 }

        /// <summary>
        /// Starts a <see cref="TagHelperExecutionContext"/> scope.
        /// </summary>
        /// <param name="tagName">The HTML tag name that the scope is associated with.</param>
        /// <param name="tagMode">HTML syntax of the element in the Razor source.</param>
        /// <param name="uniqueId">An identifier unique to the HTML element this scope is for.</param>
        /// <param name="executeChildContentAsync">A delegate used to execute the child content asynchronously.</param>
        /// <param name="startTagHelperWritingScope">A delegate used to start a writing scope in a Razor page.</param>
        /// <param name="endTagHelperWritingScope">A delegate used to end a writing scope in a Razor page.</param>
        /// <returns>A <see cref="TagHelperExecutionContext"/> to use.</returns>
        public TagHelperExecutionContext Begin(
            string tagName,
            TagMode tagMode,
            string uniqueId,
            Func<Task> executeChildContentAsync,
            Action startTagHelperWritingScope,
            Func<TagHelperContent> endTagHelperWritingScope)
        {
            if (tagName == null)
            {
                throw new ArgumentNullException(nameof(tagName));
            }

            if (uniqueId == null)
            {
                throw new ArgumentNullException(nameof(uniqueId));
            }

            if (executeChildContentAsync == null)
            {
                throw new ArgumentNullException(nameof(executeChildContentAsync));
            }

            if (startTagHelperWritingScope == null)
            {
                throw new ArgumentNullException(nameof(startTagHelperWritingScope));
            }

            if (endTagHelperWritingScope == null)
            {
                throw new ArgumentNullException(nameof(endTagHelperWritingScope));
            }

            IDictionary<object, object> items;

            // If we're not wrapped by another TagHelper, then there will not be a parentExecutionContext.
            if (_executionScopes.Count > 0)
            {
                items = new CopyOnWriteDictionary<object, object>(
                    _executionScopes.Peek().Items,
                    comparer: EqualityComparer<object>.Default);
            }
            else
            {
                items = new Dictionary<object, object>();
            }

            var executionContext = new TagHelperExecutionContext(
                tagName,
                tagMode,
                items,
                uniqueId,
                executeChildContentAsync,
                startTagHelperWritingScope,
                endTagHelperWritingScope);

            _executionScopes.Push(executionContext);

            return executionContext;
        }

        /// <summary>
        /// Instantiates a new <see cref="TagHelperExecutionContext"/>.
        /// </summary>
        /// <param name="tagName">The HTML tag name in the Razor source.</param>
        /// <param name="tagMode">HTML syntax of the element in the Razor source.</param>
        /// <param name="items">The collection of items used to communicate with other
        /// <see cref="ITagHelper"/>s</param>
        /// <param name="uniqueId">An identifier unique to the HTML element this context is for.</param>
        /// <param name="executeChildContentAsync">A delegate used to execute the child content asynchronously.</param>
        /// <param name="startTagHelperWritingScope">
        /// A delegate used to start a writing scope in a Razor page and optionally override the page's
        /// <see cref="HtmlEncoder"/> within that scope.
        /// </param>
        /// <param name="endTagHelperWritingScope">A delegate used to end a writing scope in a Razor page.</param>
        public TagHelperExecutionContext(
            string tagName,
            TagMode tagMode,
            IDictionary<object, object> items,
            string uniqueId,
            Func<Task> executeChildContentAsync,
            Action<HtmlEncoder> startTagHelperWritingScope,
            Func<TagHelperContent> endTagHelperWritingScope)
        {
            if (startTagHelperWritingScope == null)
            {
                throw new ArgumentNullException(nameof(startTagHelperWritingScope));
            }

            if (endTagHelperWritingScope == null)
            {
                throw new ArgumentNullException(nameof(endTagHelperWritingScope));
            }

            _tagHelpers = new List<ITagHelper>();
            _allAttributes = new TagHelperAttributeList();

            Context = new TagHelperContext(_allAttributes, items, uniqueId);
            Output = new TagHelperOutput(tagName, new TagHelperAttributeList(), GetChildContentAsync)
            {
                TagMode = tagMode
            };

            Reinitialize(tagName, tagMode, items, uniqueId, executeChildContentAsync);

            _startTagHelperWritingScope = startTagHelperWritingScope;
            _endTagHelperWritingScope = endTagHelperWritingScope;
        }

        /// <summary>
        /// Starts a <see cref="TagHelperExecutionContext"/> scope.
        /// </summary>
        /// <param name="tagName">The HTML tag name that the scope is associated with.</param>
        /// <param name="tagMode">HTML syntax of the element in the Razor source.</param>
        /// <param name="uniqueId">An identifier unique to the HTML element this scope is for.</param>
        /// <param name="executeChildContentAsync">A delegate used to execute the child content asynchronously.</param>
        /// <param name="startTagHelperWritingScope">A delegate used to start a writing scope in a Razor page.</param>
        /// <param name="endTagHelperWritingScope">A delegate used to end a writing scope in a Razor page.</param>
        /// <returns>A <see cref="TagHelperExecutionContext"/> to use.</returns>
        public TagHelperExecutionContext Begin(
            [NotNull] string tagName,
            TagMode tagMode,
            [NotNull] string uniqueId,
            [NotNull] Func<Task> executeChildContentAsync,
            [NotNull] Action startTagHelperWritingScope,
            [NotNull] Func<TagHelperContent> endTagHelperWritingScope)
        {
            IDictionary<object, object> items;

            // If we're not wrapped by another TagHelper, then there will not be a parentExecutionContext.
            if (_executionScopes.Count > 0)
            {
                items = new CopyOnWriteDictionary<object, object>(
                    _executionScopes.Peek().Items,
                    comparer: EqualityComparer<object>.Default);
            }
            else
            {
                items = new Dictionary<object, object>();
            }

            var executionContext = new TagHelperExecutionContext(
                tagName,
                tagMode,
                items,
                uniqueId,
                executeChildContentAsync,
                startTagHelperWritingScope,
                endTagHelperWritingScope);

            _executionScopes.Push(executionContext);

            return executionContext;
        }

        public void TagMode_ReturnsExpectedValue(TagMode tagMode)
        {
            // Arrange & Act
            var executionContext = new TagHelperExecutionContext("p", tagMode);

            // Assert
            Assert.Equal(tagMode, executionContext.TagMode);
        }

 /// <summary>
 /// Internal for testing purposes only.
 /// </summary>
 internal TagHelperExecutionContext(string tagName, TagMode tagMode)
     : this(tagName,
            tagMode,
            items: new Dictionary<object, object>(),
            uniqueId: string.Empty,
            executeChildContentAsync: async () => await Task.FromResult(result: true),
            startTagHelperWritingScope: () => { },
            endTagHelperWritingScope: () => new DefaultTagHelperContent())
 {
 }

 /// <summary>
 /// Instantiates a new <see cref="TagHelperChunk"/>.
 /// </summary>
 /// <param name="tagName">The tag name associated with the tag helpers HTML element.</param>
 /// <param name="tagMode">HTML syntax of the element in the Razor source.</param>
 /// <param name="attributes">The attributes associated with the tag helpers HTML element.</param>
 /// <param name="descriptors">
 /// The <see cref="TagHelperDescriptor"/>s associated with this tag helpers HTML element.
 /// </param>
 public TagHelperChunk(
     string tagName,
     TagMode tagMode,
     IList<KeyValuePair<string, Chunk>> attributes,
     IEnumerable<TagHelperDescriptor> descriptors)
 {
     TagName = tagName;
     TagMode = tagMode;
     Attributes = attributes;
     Descriptors = descriptors;
 }

        /// <summary>
        /// Instantiates a new <see cref="TagHelperExecutionContext"/>.
        /// </summary>
        /// <param name="tagName">The HTML tag name in the Razor source.</param>
        /// <param name="tagMode">HTML syntax of the element in the Razor source.</param>
        /// <param name="items">The collection of items used to communicate with other
        /// <see cref="ITagHelper"/>s</param>
        /// <param name="uniqueId">An identifier unique to the HTML element this context is for.</param>
        /// <param name="executeChildContentAsync">A delegate used to execute the child content asynchronously.</param>
        /// <param name="startTagHelperWritingScope">A delegate used to start a writing scope in a Razor page.</param>
        /// <param name="endTagHelperWritingScope">A delegate used to end a writing scope in a Razor page.</param>
        public TagHelperExecutionContext(
            string tagName,
            TagMode tagMode,
            IDictionary<object, object> items,
            string uniqueId,
            Func<Task> executeChildContentAsync,
            Action startTagHelperWritingScope,
            Func<TagHelperContent> endTagHelperWritingScope)
        {
            if (tagName == null)
            {
                throw new ArgumentNullException(nameof(tagName));
            }

            if (items == null)
            {
                throw new ArgumentNullException(nameof(items));
            }

            if (uniqueId == null)
            {
                throw new ArgumentNullException(nameof(uniqueId));
            }

            if (executeChildContentAsync == null)
            {
                throw new ArgumentNullException(nameof(executeChildContentAsync));
            }

            if (startTagHelperWritingScope == null)
            {
                throw new ArgumentNullException(nameof(startTagHelperWritingScope));
            }

            if (endTagHelperWritingScope == null)
            {
                throw new ArgumentNullException(nameof(endTagHelperWritingScope));
            }

            _tagHelpers = new List<ITagHelper>();
            _executeChildContentAsync = executeChildContentAsync;
            _startTagHelperWritingScope = startTagHelperWritingScope;
            _endTagHelperWritingScope = endTagHelperWritingScope;

            TagMode = tagMode;
            HTMLAttributes = new TagHelperAttributeList();
            AllAttributes = new TagHelperAttributeList();
            TagName = tagName;
            Items = items;
            UniqueId = uniqueId;
        }

 /// <summary>
 /// Instantiates a new instance of the <see cref="TagHelperBlockBuilder"/> class
 /// with the provided <paramref name="tagName"/> and derives its <see cref="Attributes"/>
 /// and <see cref="BlockBuilder.Type"/> from the <paramref name="startTag"/>.
 /// </summary>
 /// <param name="tagName">An HTML tag name.</param>
 /// <param name="tagMode">HTML syntax of the element in the Razor source.</param>
 /// <param name="start">Starting location of the <see cref="TagHelperBlock"/>.</param>
 /// <param name="attributes">Attributes of the <see cref="TagHelperBlock"/>.</param>
 /// <param name="descriptors">The <see cref="TagHelperDescriptor"/>s associated with the current HTML
 /// tag.</param>
 public TagHelperBlockBuilder(
     string tagName,
     TagMode tagMode,
     SourceLocation start,
     IList<KeyValuePair<string, SyntaxTreeNode>> attributes,
     IEnumerable<TagHelperDescriptor> descriptors)
 {
     TagName = tagName;
     TagMode = tagMode;
     Start = start;
     Descriptors = descriptors;
     Attributes = new List<KeyValuePair<string, SyntaxTreeNode>>(attributes);
     Type = BlockType.Tag;
     ChunkGenerator = new TagHelperChunkGenerator(descriptors);
 }

 /// <summary>
 /// Convert a <see cref="TagMode"/> to a string used when passing to Flickr.
 /// </summary>
 /// <param name="tagMode">The tag mode to convert.</param>
 /// <returns>The string to pass to Flickr.</returns>
 public static string TagModeToString(TagMode tagMode)
 {
     switch (tagMode)
     {
         case TagMode.None:
             return String.Empty;
         case TagMode.AllTags:
             return "all";
         case TagMode.AnyTag:
             return "any";
         case TagMode.Boolean:
             return "bool";
         default:
             return String.Empty;
     }
 }

        /// <summary>
        /// Starts a <see cref="TagHelperExecutionContext"/> scope.
        /// </summary>
        /// <param name="tagName">The HTML tag name that the scope is associated with.</param>
        /// <param name="tagMode">HTML syntax of the element in the Razor source.</param>
        /// <param name="uniqueId">An identifier unique to the HTML element this scope is for.</param>
        /// <param name="executeChildContentAsync">A delegate used to execute the child content asynchronously.</param>
        /// <returns>A <see cref="TagHelperExecutionContext"/> to use.</returns>
        public TagHelperExecutionContext Begin(
            string tagName,
            TagMode tagMode,
            string uniqueId,
            Func<Task> executeChildContentAsync)
        {
            if (tagName == null)
            {
                throw new ArgumentNullException(nameof(tagName));
            }

            if (uniqueId == null)
            {
                throw new ArgumentNullException(nameof(uniqueId));
            }

            if (executeChildContentAsync == null)
            {
                throw new ArgumentNullException(nameof(executeChildContentAsync));
            }

            IDictionary<object, object> items;
            var parentExecutionContext = _executionContextPool.Current;

            // If we're not wrapped by another TagHelper, then there will not be a parentExecutionContext.
            if (parentExecutionContext != null)
            {
                items = new CopyOnWriteDictionary<object, object>(
                    parentExecutionContext.Items,
                    comparer: EqualityComparer<object>.Default);
            }
            else
            {
                items = new Dictionary<object, object>();
            }

            var executionContext = _executionContextPool.Rent(
                tagName,
                tagMode,
                items,
                uniqueId,
                executeChildContentAsync);

            return executionContext;
        }

        public Block TagHelperBlock(
            string tagName,
            TagMode tagMode,
            SourceLocation start,
            Block startTag,
            SyntaxTreeNode[] children,
            Block endTag)
        {
            var builder = new TagHelperBlockBuilder(
                tagName,
                tagMode,
                attributes: new List<KeyValuePair<string, SyntaxTreeNode>>(),
                children: children)
            {
                Start = start,
                SourceStartTag = startTag,
                SourceEndTag = endTag
            };

            return builder.Build();
        }

        private static TagHelperOutput GetTagHelperOutput(
            string tagName,
            TagHelperAttributeList attributes,
            TagMode tagMode,
            string preElement,
            string preContent,
            string content,
            string postContent,
            string postElement)
        {
            var output = new TagHelperOutput(tagName, attributes)
            {
                TagMode = tagMode
            };

            output.PreElement.AppendEncoded(preElement);
            output.PreContent.AppendEncoded(preContent);
            output.Content.AppendEncoded(content);
            output.PostContent.AppendEncoded(postContent);
            output.PostElement.AppendEncoded(postElement);

            return output;
        }

        // Actual PhotoSearch function
        /// <summary>
        /// Search for photos.
        /// </summary>
        /// <param name="userId">The ID of the user to search the photos of.</param>
        /// <param name="tags">A comma seperated list of tags to search for.</param>
        /// <param name="tagMode">Match all tags, or any tag.</param>
        /// <param name="text">Text to search for in photo title or description.</param>
        /// <param name="perPage">Number of photos to return per page.</param>
        /// <param name="page">The page number to return.</param>
        /// <param name="extras">Optional extras to return.</param>
        /// <param name="minUploadDate">The minimum upload date.</param>
        /// <param name="maxUploadDate">The maxmimum upload date.</param>
        /// <param name="license">The license type to return.</param>
        /// <returns>A <see cref="Photos"/> instance.</returns>
        public Photos PhotosSearch(string userId, string tags, TagMode tagMode, string text, DateTime minUploadDate, DateTime maxUploadDate, int license, int perPage, int page, PhotoSearchExtras extras)
        {
            PhotoSearchOptions options = new PhotoSearchOptions();
            options.UserId = userId;
            options.Tags = tags;
            options.TagMode = tagMode;
            options.Text = text;
            options.MinUploadDate = minUploadDate;
            options.MaxUploadDate = maxUploadDate;
            if( license > 0 ) options.AddLicense(license);
            options.PerPage = perPage;
            options.Page = page;
            options.Extras = extras;

            return PhotosSearch(options);
        }

        private void RenderBeginTagHelperScope(string tagName, TagMode tagMode, IList<Chunk> children)
        {
            // Scopes/execution contexts are a runtime feature.
            if (_designTimeMode)
            {
                // Render all of the tag helper children inline for IntelliSense.
                _bodyVisitor.Accept(children);
                return;
            }

            // Call into the tag helper scope manager to start a new tag helper scope.
            // Also capture the value as the current execution context.
            _writer
                .WriteStartAssignment(ExecutionContextVariableName)
                .WriteStartInstanceMethodInvocation(
                    ScopeManagerVariableName,
                    _tagHelperContext.ScopeManagerBeginMethodName);

            // Assign a unique ID for this instance of the source HTML tag. This must be unique
            // per call site, e.g. if the tag is on the view twice, there should be two IDs.
            _writer.WriteStringLiteral(tagName)
                   .WriteParameterSeparator()
                   .Write("global::")
                   .Write(typeof(TagMode).FullName)
                   .Write(".")
                   .Write(tagMode.ToString())
                   .WriteParameterSeparator()
                   .WriteStringLiteral(GenerateUniqueId())
                   .WriteParameterSeparator();

            // We remove the target writer so TagHelper authors can retrieve content.
            var oldWriter = _context.TargetWriterName;
            _context.TargetWriterName = null;

            using (_writer.BuildAsyncLambda(endLine: false))
            {
                // Render all of the tag helper children.
                _bodyVisitor.Accept(children);
            }

            _context.TargetWriterName = oldWriter;

            _writer.WriteEndMethodInvocation();
        }

            public TagHelperExecutionContext Rent(
                string tagName,
                TagMode tagMode,
                IDictionary<object, object> items,
                string uniqueId,
                Func<Task> executeChildContentAsync)
            {
                TagHelperExecutionContext tagHelperExecutionContext;

                if (_nextIndex == _executionContexts.Count)
                {
                    tagHelperExecutionContext = new TagHelperExecutionContext(
                        tagName,
                        tagMode,
                        items,
                        uniqueId,
                        executeChildContentAsync,
                        _startTagHelperWritingScope,
                        _endTagHelperWritingScope);

                    _executionContexts.Add(tagHelperExecutionContext);
                }
                else
                {
                    tagHelperExecutionContext = _executionContexts[_nextIndex];
                    tagHelperExecutionContext.Reinitialize(tagName, tagMode, items, uniqueId, executeChildContentAsync);
                }

                _nextIndex++;

                return tagHelperExecutionContext;
            }

 public PlaceCollection PlacesPlacesForTags(string woeId, IEnumerable<string> tags, TagMode tagMode)
 {
     return PlacesPlacesForTags(PlaceType.None, woeId, null, null, tags, tagMode, null, MachineTagMode.None, null, null, null, null);
 }

        public async Task RunAsync_SetsTagHelperOutputTagMode(TagMode tagMode)
        {
            // Arrange
            var runner = new TagHelperRunner();
            var executionContext = new TagHelperExecutionContext("p", tagMode);
            var tagHelper = new TagHelperContextTouchingTagHelper();

            executionContext.Add(tagHelper);
            executionContext.AddTagHelperAttribute("foo", true);

            // Act
            var output = await runner.RunAsync(executionContext);

            // Assert
            Assert.Equal(tagMode, output.TagMode);
        }

 /// <summary>
 /// Switch the mode of a particular Tag to a mode.
 /// Valid Mode are <see cref="TagMode.Seamless"/> and <see cref="TagMode.Manual"/>
 /// </summary>
 /// <param name="name">The name of the tag to switch</param>
 /// <param name="mode">The mode to switch to</param>
 /// <exception cref="ArgumentOutOfRangeException">If the TagMode Specified is not a valid TagMode</exception>
 /// <exception cref="UnhandledException">Unhandled Exception</exception>
 /// <returns>true if the mode can be switch.</returns>
 public bool SwitchMode(string name, TagMode mode)
 {
     try
     {
         switch (mode)
         {
             case TagMode.Seamless: MonitorTag(name, true);
                 break;
             case TagMode.Manual: MonitorTag(name, false);
                 break;
             default:
                 throw new ArgumentOutOfRangeException("mode");
         }
         return true;
     }
     catch (ArgumentOutOfRangeException)
     {
         throw;
     }
     catch (Exception e)
     {
         //Handle some unexpected exception so that it does not hang the UI.
         ServiceLocator.GetLogger(ServiceLocator.DEBUG_LOG).Write(e);
         throw new UnhandledException(e);
     }
 }