From 0603cb3ab13c3466573f2092e1e89ec2649227b2 Mon Sep 17 00:00:00 2001
From: Stephan <stephane@umbraco.dk>
Date: Tue, 19 Jul 2016 13:00:14 +0200
Subject: [PATCH 1/4] U4-8720 - add IPublishedContent Site, Children ext.
 methods

---
 src/Umbraco.Web/PublishedContentExtensions.cs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/Umbraco.Web/PublishedContentExtensions.cs b/src/Umbraco.Web/PublishedContentExtensions.cs
index 578aab2755..95ae867e73 100644
--- a/src/Umbraco.Web/PublishedContentExtensions.cs
+++ b/src/Umbraco.Web/PublishedContentExtensions.cs
@@ -1746,6 +1746,11 @@ namespace Umbraco.Web
             return content.Children().Where(predicate);
         }
 
+        public static IEnumerable<IPublishedContent> Children(this IPublishedContent content, params string[] alias)
+        {
+            return content.Children(x => alias.InvariantContains(x.DocumentTypeAlias));
+        }
+
         /// <summary>
         /// Gets the children of the content, of a given content type.
         /// </summary>
@@ -1853,6 +1858,16 @@ namespace Umbraco.Web
 
         #endregion
 
+        #region Axes: custom
+
+        // todo: in v8, rename this 'Root'
+        public static IPublishedContent Site(this IPublishedContent content)
+        {
+            return content.AncestorOrSelf(1);
+        }
+
+        #endregion
+
         #region OfTypes
 
         // the .OfType<T>() filter is nice when there's only one type

From dc476dcb02823c260046907377fb4684612b86f0 Mon Sep 17 00:00:00 2001
From: Stephan <stephane@umbraco.dk>
Date: Tue, 19 Jul 2016 13:00:43 +0200
Subject: [PATCH 2/4] U4-8720 - get typed content by guid

---
 .../ITypedPublishedContentQuery.cs            |  8 +++++
 src/Umbraco.Web/PublishedContentQuery.cs      | 33 ++++++++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/src/Umbraco.Web/ITypedPublishedContentQuery.cs b/src/Umbraco.Web/ITypedPublishedContentQuery.cs
index aefe243a0b..63bb2dabe3 100644
--- a/src/Umbraco.Web/ITypedPublishedContentQuery.cs
+++ b/src/Umbraco.Web/ITypedPublishedContentQuery.cs
@@ -1,3 +1,4 @@
+using System;
 using System.Collections.Generic;
 using System.Xml.XPath;
 using Umbraco.Core.Models;
@@ -11,14 +12,21 @@ namespace Umbraco.Web
     public interface ITypedPublishedContentQuery
     {
         IPublishedContent TypedContent(int id);
+        IPublishedContent TypedContent(Guid id);
         IPublishedContent TypedContentSingleAtXPath(string xpath, params XPathVariable[] vars);
         IEnumerable<IPublishedContent> TypedContent(IEnumerable<int> ids);
+        IEnumerable<IPublishedContent> TypedContent(IEnumerable<Guid> ids);
         IEnumerable<IPublishedContent> TypedContentAtXPath(string xpath, params XPathVariable[] vars);
         IEnumerable<IPublishedContent> TypedContentAtXPath(XPathExpression xpath, params XPathVariable[] vars);
         IEnumerable<IPublishedContent> TypedContentAtRoot();
 
+        // note: we CANNOT implement TypedMedia in v7 without break-changing IPublishedCache,
+        // since we don't support XPath navigation of the media tree.
+
         IPublishedContent TypedMedia(int id);
+        //IPublishedContent TypedMedia(Guid id);
         IEnumerable<IPublishedContent> TypedMedia(IEnumerable<int> ids);
+        //IEnumerable<IPublishedContent> TypedMedia(IEnumerable<Guid> ids);
         IEnumerable<IPublishedContent> TypedMediaAtRoot();
 
         /// <summary>
diff --git a/src/Umbraco.Web/PublishedContentQuery.cs b/src/Umbraco.Web/PublishedContentQuery.cs
index 16f42b8197..4966310c0f 100644
--- a/src/Umbraco.Web/PublishedContentQuery.cs
+++ b/src/Umbraco.Web/PublishedContentQuery.cs
@@ -2,7 +2,9 @@
 using System.Collections.Generic;
 using System.Linq;
 using System.Xml.XPath;
+using umbraco;
 using Umbraco.Core;
+using Umbraco.Core.Configuration;
 using Umbraco.Core.Dynamics;
 using Umbraco.Core.Models;
 using Umbraco.Core.Xml;
@@ -56,6 +58,13 @@ namespace Umbraco.Web
                 : _typedContentQuery.TypedContent(id);
         }
 
+        public IPublishedContent TypedContent(Guid id)
+        {
+            return _typedContentQuery == null
+                ? TypedDocumentById(id, _contentCache)
+                : _typedContentQuery.TypedContent(id);
+        }
+
         public IPublishedContent TypedContentSingleAtXPath(string xpath, params XPathVariable[] vars)
         {
             return _typedContentQuery == null
@@ -70,6 +79,13 @@ namespace Umbraco.Web
                 : _typedContentQuery.TypedContent(ids);
         }
 
+        public IEnumerable<IPublishedContent> TypedContent(IEnumerable<Guid> ids)
+        {
+            return _typedContentQuery == null
+                ? TypedDocumentsByIds(_contentCache, ids)
+                : _typedContentQuery.TypedContent(ids);
+        }
+
         public IEnumerable<IPublishedContent> TypedContentAtXPath(string xpath, params XPathVariable[] vars)
         {
             return _typedContentQuery == null
@@ -150,7 +166,7 @@ namespace Umbraco.Web
                 ? TypedDocumentById(id, _mediaCache)
                 : _typedContentQuery.TypedMedia(id);
         }
-        
+
         public IEnumerable<IPublishedContent> TypedMedia(IEnumerable<int> ids)
         {
             return _typedContentQuery == null
@@ -196,6 +212,15 @@ namespace Umbraco.Web
             return doc;
         }
 
+        private IPublishedContent TypedDocumentById(Guid id, ContextualPublishedCache cache)
+        {
+            // todo: in v8, implement in a more efficient way
+            var legacyXml = UmbracoConfig.For.UmbracoSettings().Content.UseLegacyXmlSchema;
+            var xpath = legacyXml ? "//node [@key=$guid]" : "//* [@isDoc and @key=$guid]";
+            var doc = cache.GetSingleByXPath(xpath, new XPathVariable("guid", id.ToString()));
+            return doc;
+        }
+
         private IPublishedContent TypedDocumentByXPath(string xpath, XPathVariable[] vars, ContextualPublishedContentCache cache)
         {
             var doc = cache.GetSingleByXPath(xpath, vars);
@@ -214,6 +239,12 @@ namespace Umbraco.Web
             return ids.Select(eachId => TypedDocumentById(eachId, cache)).WhereNotNull();
         }
 
+        private IEnumerable<IPublishedContent> TypedDocumentsByIds(ContextualPublishedCache cache, IEnumerable<Guid> ids)
+        {
+            // todo: in v8, implement in a more efficient way
+            return ids.Select(eachId => TypedDocumentById(eachId, cache)).WhereNotNull();
+        }
+
         private IEnumerable<IPublishedContent> TypedDocumentsByXPath(string xpath, XPathVariable[] vars, ContextualPublishedContentCache cache)
         {
             var doc = cache.GetByXPath(xpath, vars);

From a0caab410ec441d173856411291c09ec536c19ec Mon Sep 17 00:00:00 2001
From: Stephan <stephane@umbraco.dk>
Date: Tue, 19 Jul 2016 16:13:46 +0200
Subject: [PATCH 3/4] U4-8720 - add dynamic support, UmbracoHelper methods

---
 .../IDynamicPublishedContentQuery.cs          |  10 +-
 .../ITypedPublishedContentQuery.cs            |   2 +-
 src/Umbraco.Web/PublishedContentQuery.cs      |  33 ++-
 src/Umbraco.Web/UmbracoHelper.cs              | 220 +++++++++++++-----
 4 files changed, 207 insertions(+), 58 deletions(-)

diff --git a/src/Umbraco.Web/IDynamicPublishedContentQuery.cs b/src/Umbraco.Web/IDynamicPublishedContentQuery.cs
index 051ba07ff6..7c95fd7e2e 100644
--- a/src/Umbraco.Web/IDynamicPublishedContentQuery.cs
+++ b/src/Umbraco.Web/IDynamicPublishedContentQuery.cs
@@ -1,3 +1,4 @@
+using System;
 using System.Collections.Generic;
 using System.Xml.XPath;
 using Umbraco.Core.Xml;
@@ -10,15 +11,22 @@ namespace Umbraco.Web
     public interface IDynamicPublishedContentQuery
     {
         dynamic Content(int id);
+        dynamic Content(Guid id);
         dynamic ContentSingleAtXPath(string xpath, params XPathVariable[] vars);
         dynamic ContentSingleAtXPath(XPathExpression xpath, params XPathVariable[] vars);
         dynamic Content(IEnumerable<int> ids);
+        dynamic Content(IEnumerable<Guid> ids);
         dynamic ContentAtXPath(string xpath, params XPathVariable[] vars);
         dynamic ContentAtXPath(XPathExpression xpath, params XPathVariable[] vars);
         dynamic ContentAtRoot();
-        
+
+        // note: we CANNOT implement Media by Guid in v7 without break-changing IPublishedCache,
+        // since we don't support XPath navigation of the media tree.
+
         dynamic Media(int id);
+        //dynamic Media(Guid id);
         dynamic Media(IEnumerable<int> ids);
+        //dynamic Media(IEnumerable<Guid> ids);
         dynamic MediaAtRoot();
 
         /// <summary>
diff --git a/src/Umbraco.Web/ITypedPublishedContentQuery.cs b/src/Umbraco.Web/ITypedPublishedContentQuery.cs
index 63bb2dabe3..7a2be964f7 100644
--- a/src/Umbraco.Web/ITypedPublishedContentQuery.cs
+++ b/src/Umbraco.Web/ITypedPublishedContentQuery.cs
@@ -20,7 +20,7 @@ namespace Umbraco.Web
         IEnumerable<IPublishedContent> TypedContentAtXPath(XPathExpression xpath, params XPathVariable[] vars);
         IEnumerable<IPublishedContent> TypedContentAtRoot();
 
-        // note: we CANNOT implement TypedMedia in v7 without break-changing IPublishedCache,
+        // note: we CANNOT implement TypedMedia by Guid in v7 without break-changing IPublishedCache,
         // since we don't support XPath navigation of the media tree.
 
         IPublishedContent TypedMedia(int id);
diff --git a/src/Umbraco.Web/PublishedContentQuery.cs b/src/Umbraco.Web/PublishedContentQuery.cs
index 4966310c0f..f0f2461ad8 100644
--- a/src/Umbraco.Web/PublishedContentQuery.cs
+++ b/src/Umbraco.Web/PublishedContentQuery.cs
@@ -113,7 +113,14 @@ namespace Umbraco.Web
                 ? DocumentById(id, _contentCache, DynamicNull.Null)
                 : _dynamicContentQuery.Content(id);
         }
-        
+
+        public dynamic Content(Guid id)
+        {
+            return _dynamicContentQuery == null
+                ? DocumentById(id, _contentCache, DynamicNull.Null)
+                : _dynamicContentQuery.Content(id);
+        }
+
         public dynamic ContentSingleAtXPath(string xpath, params XPathVariable[] vars)
         {
             return _dynamicContentQuery == null
@@ -135,6 +142,13 @@ namespace Umbraco.Web
                 : _dynamicContentQuery.Content(ids);
         }
 
+        public dynamic Content(IEnumerable<Guid> ids)
+        {
+            return _dynamicContentQuery == null
+                ? DocumentByIds(_contentCache, ids.ToArray())
+                : _dynamicContentQuery.Content(ids);
+        }
+
         public dynamic ContentAtXPath(string xpath, params XPathVariable[] vars)
         {
             return _dynamicContentQuery == null
@@ -270,6 +284,14 @@ namespace Umbraco.Web
                        : new DynamicPublishedContent(doc).AsDynamic();
         }
 
+        private dynamic DocumentById(Guid id, ContextualPublishedCache cache, object ifNotFound)
+        {
+            var doc = TypedDocumentById(id, cache);
+            return doc == null
+                       ? ifNotFound
+                       : new DynamicPublishedContent(doc).AsDynamic();
+        }
+
         private dynamic DocumentByXPath(string xpath, XPathVariable[] vars, ContextualPublishedCache cache, object ifNotFound)
         {
             var doc = cache.GetSingleByXPath(xpath, vars);
@@ -295,6 +317,15 @@ namespace Umbraco.Web
             return new DynamicPublishedContentList(nodes);
         }
 
+        private dynamic DocumentByIds(ContextualPublishedCache cache, IEnumerable<Guid> ids)
+        {
+            var dNull = DynamicNull.Null;
+            var nodes = ids.Select(eachId => DocumentById(eachId, cache, dNull))
+                           .Where(x => TypeHelper.IsTypeAssignableFrom<DynamicNull>(x) == false)
+                           .Cast<DynamicPublishedContent>();
+            return new DynamicPublishedContentList(nodes);
+        }
+
         private dynamic DocumentsByXPath(string xpath, XPathVariable[] vars, ContextualPublishedCache cache)
         {
             return new DynamicPublishedContentList(
diff --git a/src/Umbraco.Web/UmbracoHelper.cs b/src/Umbraco.Web/UmbracoHelper.cs
index 165b81daba..587c821daa 100644
--- a/src/Umbraco.Web/UmbracoHelper.cs
+++ b/src/Umbraco.Web/UmbracoHelper.cs
@@ -15,6 +15,7 @@ using Umbraco.Web.Routing;
 using Umbraco.Web.Security;
 using System.Collections.Generic;
 using System.IO;
+using System.Linq;
 using System.Web.Mvc;
 using System.Web.Routing;
 using Umbraco.Core.Cache;
@@ -561,21 +562,35 @@ namespace Umbraco.Web
         #region Content
 
         public IPublishedContent TypedContent(object id)
-		{
-		    int intId;
-            return ConvertIdObjectToInt(id, out intId) ? ContentQuery.TypedContent(intId) : null;
+        {
+            return TypedContentForObject(id);
 		}
 
-		public IPublishedContent TypedContent(int id)
+        private IPublishedContent TypedContentForObject(object id)
+        {
+            int intId;
+            if (ConvertIdObjectToInt(id, out intId))
+                return ContentQuery.TypedContent(intId);
+            Guid guidId;
+            if (ConvertIdObjectToGuid(id, out guidId))
+                return ContentQuery.TypedContent(guidId);
+            return null;
+        }
+
+        public IPublishedContent TypedContent(int id)
 		{
             return ContentQuery.TypedContent(id);
 		}
 
+        public IPublishedContent TypedContent(Guid id)
+        {
+            return ContentQuery.TypedContent(id);
+        }
+
 		public IPublishedContent TypedContent(string id)
 		{
-            int intId;
-            return ConvertIdObjectToInt(id, out intId) ? ContentQuery.TypedContent(intId) : null;
-		}
+            return TypedContentForObject(id);
+        }
 
         public IPublishedContent TypedContentSingleAtXPath(string xpath, params XPathVariable[] vars)
         {
@@ -584,9 +599,21 @@ namespace Umbraco.Web
 
 		public IEnumerable<IPublishedContent> TypedContent(params object[] ids)
 		{
-            return ContentQuery.TypedContent(ConvertIdsObjectToInts(ids));
+		    return TypedContentForObjects(ids);
 		}
 
+        private IEnumerable<IPublishedContent> TypedContentForObjects(IEnumerable<object> ids)
+        {
+            var idsA = ids.ToArray();
+            IEnumerable<int> intIds;
+            if (ConvertIdsObjectToInts(idsA, out intIds))
+                return ContentQuery.TypedContent(intIds);
+            IEnumerable<Guid> guidIds;
+            if (ConvertIdsObjectToGuids(idsA, out guidIds))
+                return ContentQuery.TypedContent(guidIds);
+            return Enumerable.Empty<IPublishedContent>();
+        }
+
         /// <summary>
         /// Gets the contents corresponding to the identifiers.
         /// </summary>
@@ -598,6 +625,11 @@ namespace Umbraco.Web
             return ContentQuery.TypedContent(ids);
 		}
 
+        public IEnumerable<IPublishedContent> TypedContent(params Guid[] ids)
+        {
+            return ContentQuery.TypedContent(ids);
+        }
+
         /// <summary>
         /// Gets the contents corresponding to the identifiers.
         /// </summary>
@@ -605,8 +637,8 @@ namespace Umbraco.Web
         /// <returns>The existing contents corresponding to the identifiers.</returns>
         /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
         public IEnumerable<IPublishedContent> TypedContent(params string[] ids)
-		{
-            return ContentQuery.TypedContent(ConvertIdsObjectToInts(ids));
+        {
+            return TypedContentForObjects(ids);
 		}
 
         /// <summary>
@@ -616,8 +648,8 @@ namespace Umbraco.Web
         /// <returns>The existing contents corresponding to the identifiers.</returns>
         /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
         public IEnumerable<IPublishedContent> TypedContent(IEnumerable<object> ids)
-		{
-            return ContentQuery.TypedContent(ConvertIdsObjectToInts(ids));
+        {
+            return TypedContentForObjects(ids);
 		}
 
         /// <summary>
@@ -628,7 +660,7 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
         public IEnumerable<IPublishedContent> TypedContent(IEnumerable<string> ids)
 		{
-            return ContentQuery.TypedContent(ConvertIdsObjectToInts(ids));
+            return TypedContentForObjects(ids);
 		}
 
         /// <summary>
@@ -659,20 +691,29 @@ namespace Umbraco.Web
 
 		public dynamic Content(object id)
 		{
-            int intId;
-            return ConvertIdObjectToInt(id, out intId) ? ContentQuery.Content(intId) : DynamicNull.Null;
+		    return ContentForObject(id);
 		}
 
-		public dynamic Content(int id)
+        private dynamic ContentForObject(object id)
+        {
+            int intId;
+            if (ConvertIdObjectToInt(id, out intId))
+                return ContentQuery.Content(intId);
+            Guid guidId;
+            if (ConvertIdObjectToGuid(id, out guidId))
+                return ContentQuery.Content(guidId);
+            return DynamicNull.Null;
+        }
+
+        public dynamic Content(int id)
 		{
             return ContentQuery.Content(id);
 		}
 
 		public dynamic Content(string id)
 		{
-            int intId;
-            return ConvertIdObjectToInt(id, out intId) ? ContentQuery.Content(intId) : DynamicNull.Null;
-		}
+            return ContentForObject(id);
+        }
 
         public dynamic ContentSingleAtXPath(string xpath, params XPathVariable[] vars)
         {
@@ -691,9 +732,21 @@ namespace Umbraco.Web
         /// <returns>The existing contents corresponding to the identifiers.</returns>
         /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
         public dynamic Content(params object[] ids)
-		{
-            return ContentQuery.Content(ConvertIdsObjectToInts(ids));
-		}
+        {
+            return ContentForObjects(ids);
+        }
+
+        private dynamic ContentForObjects(IEnumerable<object> ids)
+        {
+            var idsA = ids.ToArray();
+            IEnumerable<int> intIds;
+            if (ConvertIdsObjectToInts(idsA, out intIds))
+                return ContentQuery.Content(intIds);
+            IEnumerable<Guid> guidIds;
+            if (ConvertIdsObjectToGuids(idsA, out guidIds))
+                return ContentQuery.Content(guidIds);
+            return Enumerable.Empty<IPublishedContent>();
+        }
 
         /// <summary>
         /// Gets the contents corresponding to the identifiers.
@@ -714,8 +767,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
         public dynamic Content(params string[] ids)
 		{
-            return ContentQuery.Content(ConvertIdsObjectToInts(ids));
-		}
+            return ContentForObjects(ids);
+        }
 
         /// <summary>
         /// Gets the contents corresponding to the identifiers.
@@ -725,8 +778,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
         public dynamic Content(IEnumerable<object> ids)
 		{
-            return ContentQuery.Content(ConvertIdsObjectToInts(ids));
-		}
+            return ContentForObjects(ids);
+        }
 
         /// <summary>
         /// Gets the contents corresponding to the identifiers.
@@ -747,8 +800,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
         public dynamic Content(IEnumerable<string> ids)
 		{
-            return ContentQuery.Content(ConvertIdsObjectToInts(ids));
-		}
+            return ContentForObjects(ids);
+        }
 
         public dynamic ContentAtXPath(string xpath, params XPathVariable[] vars)
         {
@@ -765,35 +818,68 @@ namespace Umbraco.Web
             return ContentQuery.ContentAtRoot();
         }
 
-        private bool ConvertIdObjectToInt(object id, out int intId)
+        private static bool ConvertIdObjectToInt(object id, out int intId)
         {
             var s = id as string;
             if (s != null)
             {
                 return int.TryParse(s, out intId);
-            }
-                
+            }               
             if (id is int)
             {
                 intId = (int) id;
                 return true;
             }
-
-            throw new InvalidOperationException("The value of parameter 'id' must be either a string or an integer");
+            intId = default(int);
+            return false;
         }
 
-        private IEnumerable<int> ConvertIdsObjectToInts(IEnumerable<object> ids)
+        private static bool ConvertIdObjectToGuid(object id, out Guid guidId)
+        {
+            var s = id as string;
+            if (s != null)
+            {
+                return Guid.TryParse(s, out guidId);
+            }
+            if (id is Guid)
+            {
+                guidId = (Guid) id;
+                return true;
+            }
+            guidId = default(Guid);
+            return false;
+        }
+
+        private static bool ConvertIdsObjectToInts(IEnumerable<object> ids, out IEnumerable<int> intIds)
         {
             var list = new List<int>();
+            intIds = null;
             foreach (var id in ids)
             {
                 int intId;
                 if (ConvertIdObjectToInt(id, out intId))
-                {
                     list.Add(intId);
-                }
+                else
+                    return false; // if one of them is not an int, fail
             }
-            return list;
+            intIds = list;
+            return true;
+        }
+
+        private static bool ConvertIdsObjectToGuids(IEnumerable<object> ids, out IEnumerable<Guid> guidIds)
+        {
+            var list = new List<Guid>();
+            guidIds = null;
+            foreach (var id in ids)
+            {
+                Guid guidId;
+                if (ConvertIdObjectToGuid(id, out guidId))
+                    list.Add(guidId);
+                else
+                    return false; // if one of them is not a guid, fail
+            }
+            guidIds = list;
+            return true;
         }
 
 		#endregion
@@ -834,9 +920,21 @@ namespace Umbraco.Web
         /// <returns>The existing medias corresponding to the identifiers.</returns>
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public IEnumerable<IPublishedContent> TypedMedia(params object[] ids)
-		{
-            return ContentQuery.TypedMedia(ConvertIdsObjectToInts(ids));
-		}
+        {
+            return TypedMediaForObjects(ids);
+        }
+
+        private IEnumerable<IPublishedContent> TypedMediaForObjects(IEnumerable<object> ids)
+        {
+            var idsA = ids.ToArray();
+            IEnumerable<int> intIds;
+            if (ConvertIdsObjectToInts(idsA, out intIds))
+                return ContentQuery.TypedMedia(intIds);
+            //IEnumerable<Guid> guidIds;
+            //if (ConvertIdsObjectToGuids(idsA, out guidIds))
+            //    return ContentQuery.TypedMedia(guidIds);
+            return Enumerable.Empty<IPublishedContent>();
+        }
 
         /// <summary>
         /// Gets the medias corresponding to the identifiers.
@@ -857,8 +955,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public IEnumerable<IPublishedContent> TypedMedia(params string[] ids)
 		{
-            return ContentQuery.TypedMedia(ConvertIdsObjectToInts(ids));
-		}
+            return TypedMediaForObjects(ids);
+        }
 
         /// <summary>
         /// Gets the medias corresponding to the identifiers.
@@ -868,8 +966,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public IEnumerable<IPublishedContent> TypedMedia(IEnumerable<object> ids)
 		{
-            return ContentQuery.TypedMedia(ConvertIdsObjectToInts(ids));
-		}
+            return TypedMediaForObjects(ids);
+        }
 
         /// <summary>
         /// Gets the medias corresponding to the identifiers.
@@ -890,8 +988,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public IEnumerable<IPublishedContent> TypedMedia(IEnumerable<string> ids)
 		{
-            return ContentQuery.TypedMedia(ConvertIdsObjectToInts(ids));
-		}
+            return TypedMediaForObjects(ids);
+        }
 
         public IEnumerable<IPublishedContent> TypedMediaAtRoot()
         {
@@ -922,9 +1020,21 @@ namespace Umbraco.Web
         /// <returns>The existing medias corresponding to the identifiers.</returns>
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public dynamic Media(params object[] ids)
-		{
-            return ContentQuery.Media(ConvertIdsObjectToInts(ids));
-		}
+        {
+            return MediaForObjects(ids);
+        }
+
+        private dynamic MediaForObjects(IEnumerable<object> ids)
+        {
+            var idsA = ids.ToArray();
+            IEnumerable<int> intIds;
+            if (ConvertIdsObjectToInts(idsA, out intIds))
+                return ContentQuery.Media(intIds);
+            //IEnumerable<Guid> guidIds;
+            //if (ConvertIdsObjectToGuids(idsA, out guidIds))
+            //    return ContentQuery.Media(guidIds);
+            return Enumerable.Empty<IPublishedContent>();
+        }
 
         /// <summary>
         /// Gets the medias corresponding to the identifiers.
@@ -944,8 +1054,8 @@ namespace Umbraco.Web
         /// <returns>The existing medias corresponding to the identifiers.</returns>
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public dynamic Media(params string[] ids)
-		{
-            return ContentQuery.Media(ConvertIdsObjectToInts(ids));
+        {
+            return MediaForObjects(ids);
 		}
 
         /// <summary>
@@ -956,8 +1066,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public dynamic Media(IEnumerable<object> ids)
 		{
-            return ContentQuery.Media(ConvertIdsObjectToInts(ids));
-		}
+            return MediaForObjects(ids);
+        }
 
         /// <summary>
         /// Gets the medias corresponding to the identifiers.
@@ -978,8 +1088,8 @@ namespace Umbraco.Web
         /// <remarks>If an identifier does not match an existing media, it will be missing in the returned value.</remarks>
         public dynamic Media(IEnumerable<string> ids)
 		{
-            return ContentQuery.Media(ConvertIdsObjectToInts(ids));
-		}
+            return MediaForObjects(ids);
+        }
 
         public dynamic MediaAtRoot()
         {

From 6c6c56645d9df4b5e5efcb9a32414ac0125d619f Mon Sep 17 00:00:00 2001
From: Stephan <stephane@umbraco.dk>
Date: Thu, 21 Jul 2016 15:20:45 +0200
Subject: [PATCH 4/4] U4-8720 - add documentation

---
 .../Models/DynamicPublishedContent.cs         |   6 +-
 src/Umbraco.Web/PublishedContentExtensions.cs |  11 ++
 src/Umbraco.Web/UmbracoHelper.cs              | 143 ++++++++++++------
 3 files changed, 106 insertions(+), 54 deletions(-)

diff --git a/src/Umbraco.Web/Models/DynamicPublishedContent.cs b/src/Umbraco.Web/Models/DynamicPublishedContent.cs
index 26a5517039..141eeefae1 100644
--- a/src/Umbraco.Web/Models/DynamicPublishedContent.cs
+++ b/src/Umbraco.Web/Models/DynamicPublishedContent.cs
@@ -1101,11 +1101,9 @@ namespace Umbraco.Web.Models
         }
 
         /// <summary>
-        /// A shortcut method for AncestorOrSelf(1)
+        /// Gets the 'site' content for this content.
         /// </summary>
-        /// <returns>
-        /// The site homepage
-        /// </returns>
+        /// <returns>The 'site' content ie AncestorOrSelf(1).</returns>
 	    public DynamicPublishedContent Site()
 	    {
             return AncestorOrSelf(1);
diff --git a/src/Umbraco.Web/PublishedContentExtensions.cs b/src/Umbraco.Web/PublishedContentExtensions.cs
index 95ae867e73..5caa08729a 100644
--- a/src/Umbraco.Web/PublishedContentExtensions.cs
+++ b/src/Umbraco.Web/PublishedContentExtensions.cs
@@ -1746,6 +1746,12 @@ namespace Umbraco.Web
             return content.Children().Where(predicate);
         }
 
+        /// <summary>
+        /// Gets the children of the content, of any of the specified types.
+        /// </summary>
+        /// <param name="content">The content.</param>
+        /// <param name="alias">One or more content type alias.</param>
+        /// <returns>The children of the content, of any of the specified types.</returns>
         public static IEnumerable<IPublishedContent> Children(this IPublishedContent content, params string[] alias)
         {
             return content.Children(x => alias.InvariantContains(x.DocumentTypeAlias));
@@ -1861,6 +1867,11 @@ namespace Umbraco.Web
         #region Axes: custom
 
         // todo: in v8, rename this 'Root'
+        /// <summary>
+        /// Gets the 'site' content for this content.
+        /// </summary>
+        /// <param name="content">The content.</param>
+        /// <returns>The 'site' content ie AncestorOrSelf(1).</returns>
         public static IPublishedContent Site(this IPublishedContent content)
         {
             return content.AncestorOrSelf(1);
diff --git a/src/Umbraco.Web/UmbracoHelper.cs b/src/Umbraco.Web/UmbracoHelper.cs
index 587c821daa..2508d47b58 100644
--- a/src/Umbraco.Web/UmbracoHelper.cs
+++ b/src/Umbraco.Web/UmbracoHelper.cs
@@ -30,10 +30,10 @@ namespace Umbraco.Web
 		private readonly UmbracoContext _umbracoContext;
 		private readonly IPublishedContent _currentPage;
         private readonly ITypedPublishedContentQuery _typedQuery;
-        private readonly IDynamicPublishedContentQuery _dynamicQuery;       
+        private readonly IDynamicPublishedContentQuery _dynamicQuery;
         private readonly HtmlStringUtilities _stringUtilities = new HtmlStringUtilities();
 
-        private IUmbracoComponentRenderer _componentRenderer;        
+        private IUmbracoComponentRenderer _componentRenderer;
         private PublishedContentQuery _query;
         private MembershipHelper _membershipHelper;
         private TagQuery _tag;
@@ -224,7 +224,7 @@ namespace Umbraco.Web
         {
             if (query == null) throw new ArgumentNullException("query");
             _query = query;
-        } 
+        }
         #endregion
 
         /// <summary>
@@ -233,7 +233,7 @@ namespace Umbraco.Web
         /// <remarks>
         /// Note that this is the assigned IPublishedContent item to the UmbracoHelper, this is not necessarily the Current IPublishedContent item
         /// being rendered. This IPublishedContent object is contextual to the current UmbracoHelper instance.
-        /// 
+        ///
         /// In some cases accessing this property will throw an exception if there is not IPublishedContent assigned to the Helper
         /// this will only ever happen if the Helper is constructed with an UmbracoContext and it is not a front-end request
         /// </remarks>
@@ -244,7 +244,7 @@ namespace Umbraco.Web
 	        {
 	            if (_currentPage == null)
                     throw new InvalidOperationException("Cannot return the " + typeof(IPublishedContent).Name + " because the " + typeof(UmbracoHelper).Name + " was constructed with an " + typeof(UmbracoContext).Name + " and the current request is not a front-end request.");
-                
+
                 return _currentPage;
 	        }
 	    }
@@ -316,15 +316,15 @@ namespace Umbraco.Web
         /// <param name="formatAsDateWithTimeSeparator"></param>
         //// <param name="formatString"></param>
 		/// <returns></returns>
-		public IHtmlString Field(string fieldAlias, 
+		public IHtmlString Field(string fieldAlias,
 			string altFieldAlias = "", string altText = "", string insertBefore = "", string insertAfter = "",
 			bool recursive = false, bool convertLineBreaks = false, bool removeParagraphTags = false,
 			RenderFieldCaseType casing = RenderFieldCaseType.Unchanged,
-            RenderFieldEncodingType encoding = RenderFieldEncodingType.Unchanged, 
-            bool formatAsDate = false, 
+            RenderFieldEncodingType encoding = RenderFieldEncodingType.Unchanged,
+            bool formatAsDate = false,
             bool formatAsDateWithTime = false,
             string formatAsDateWithTimeSeparator = "")
-		{			
+		{
             return UmbracoComponentRenderer.Field(AssignedContentItem, fieldAlias, altFieldAlias,
                 altText, insertBefore, insertAfter, recursive, convertLineBreaks, removeParagraphTags,
                 casing, encoding, formatAsDate, formatAsDateWithTime, formatAsDateWithTimeSeparator);
@@ -349,11 +349,11 @@ namespace Umbraco.Web
         /// <param name="formatAsDateWithTimeSeparator"></param>
 		//// <param name="formatString"></param>
 		/// <returns></returns>
-		public IHtmlString Field(IPublishedContent currentPage, string fieldAlias, 
+		public IHtmlString Field(IPublishedContent currentPage, string fieldAlias,
 			string altFieldAlias = "", string altText = "", string insertBefore = "", string insertAfter = "",
 			bool recursive = false, bool convertLineBreaks = false, bool removeParagraphTags = false,
 			RenderFieldCaseType casing = RenderFieldCaseType.Unchanged,
-			RenderFieldEncodingType encoding = RenderFieldEncodingType.Unchanged, 
+			RenderFieldEncodingType encoding = RenderFieldEncodingType.Unchanged,
             bool formatAsDate =  false,
             bool formatAsDateWithTime = false,
             string formatAsDateWithTimeSeparator = "")
@@ -425,7 +425,7 @@ namespace Umbraco.Web
         /// Check if the current user has access to a document
         /// </summary>
         /// <param name="path">The full path of the document object to check</param>
-        /// <returns>True if the current user has access or if the current document isn't protected</returns>        
+        /// <returns>True if the current user has access or if the current document isn't protected</returns>
         public bool MemberHasAccess(string path)
         {
             if (IsProtected(path))
@@ -456,7 +456,7 @@ namespace Umbraco.Web
 		public bool MemberIsLoggedOn()
 		{
             return MembershipHelper.IsLoggedIn();
-		} 
+		}
 
 		#endregion
 
@@ -496,7 +496,7 @@ namespace Umbraco.Web
 	    }
 
 		/// <summary>
-		/// This method will always add the domain to the path if the hostnames are set up correctly. 
+		/// This method will always add the domain to the path if the hostnames are set up correctly.
 		/// </summary>
 		/// <param name="nodeId">Identifier for the node that should be returned</param>
 		/// <returns>String with a friendly url with full domain from a node</returns>
@@ -561,6 +561,11 @@ namespace Umbraco.Web
 
         #region Content
 
+        /// <summary>
+        /// Gets a content item from the cache.
+        /// </summary>
+        /// <param name="id">The unique identifier, or the key, of the content item.</param>
+        /// <returns>The content, or null of the content item is not in the cache.</returns>
         public IPublishedContent TypedContent(object id)
         {
             return TypedContentForObject(id);
@@ -577,16 +582,31 @@ namespace Umbraco.Web
             return null;
         }
 
+        /// <summary>
+        /// Gets a content item from the cache.
+        /// </summary>
+        /// <param name="id">The unique identifier of the content item.</param>
+        /// <returns>The content, or null of the content item is not in the cache.</returns>
         public IPublishedContent TypedContent(int id)
 		{
             return ContentQuery.TypedContent(id);
 		}
 
+        /// <summary>
+        /// Gets a content item from the cache.
+        /// </summary>
+        /// <param name="id">The key of the content item.</param>
+        /// <returns>The content, or null of the content item is not in the cache.</returns>
         public IPublishedContent TypedContent(Guid id)
         {
             return ContentQuery.TypedContent(id);
         }
 
+        /// <summary>
+        /// Gets a content item from the cache.
+        /// </summary>
+        /// <param name="id">The unique identifier, or the key, of the content item.</param>
+        /// <returns>The content, or null of the content item is not in the cache.</returns>
 		public IPublishedContent TypedContent(string id)
 		{
             return TypedContentForObject(id);
@@ -597,6 +617,12 @@ namespace Umbraco.Web
             return ContentQuery.TypedContentSingleAtXPath(xpath, vars);
         }
 
+        /// <summary>
+        /// Gets content items from the cache.
+        /// </summary>
+        /// <param name="ids">The unique identifiers, or the keys, of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
+        /// <remarks>Does not support mixing identifiers and keys.</remarks>
 		public IEnumerable<IPublishedContent> TypedContent(params object[] ids)
 		{
 		    return TypedContentForObjects(ids);
@@ -615,27 +641,31 @@ namespace Umbraco.Web
         }
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
 		public IEnumerable<IPublishedContent> TypedContent(params int[] ids)
 		{
             return ContentQuery.TypedContent(ids);
 		}
 
+        /// <summary>
+        /// Gets content items from the cache.
+        /// </summary>
+        /// <param name="ids">The keys of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
         public IEnumerable<IPublishedContent> TypedContent(params Guid[] ids)
         {
             return ContentQuery.TypedContent(ids);
         }
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers, or the keys, of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
+        /// <remarks>Does not support mixing identifiers and keys.</remarks>
         public IEnumerable<IPublishedContent> TypedContent(params string[] ids)
         {
             return TypedContentForObjects(ids);
@@ -689,6 +719,11 @@ namespace Umbraco.Web
             return ContentQuery.TypedContentAtRoot();
         }
 
+        /// <summary>
+        /// Gets a content item from the cache.
+        /// </summary>
+        /// <param name="id">The unique identifier, or the key, of the content item.</param>
+        /// <returns>The content, or DynamicNull of the content item is not in the cache.</returns>
 		public dynamic Content(object id)
 		{
 		    return ContentForObject(id);
@@ -705,11 +740,21 @@ namespace Umbraco.Web
             return DynamicNull.Null;
         }
 
+        /// <summary>
+        /// Gets a content item from the cache.
+        /// </summary>
+        /// <param name="id">The unique identifier of the content item.</param>
+        /// <returns>The content, or DynamicNull of the content item is not in the cache.</returns>
         public dynamic Content(int id)
 		{
             return ContentQuery.Content(id);
 		}
 
+        /// <summary>
+        /// Gets a content item from the cache.
+        /// </summary>
+        /// <param name="id">The unique identifier, or the key, of the content item.</param>
+        /// <returns>The content, or DynamicNull of the content item is not in the cache.</returns>
 		public dynamic Content(string id)
 		{
             return ContentForObject(id);
@@ -726,11 +771,11 @@ namespace Umbraco.Web
         }
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers, or the keys, of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
+        /// <remarks>Does not support mixing identifiers and keys.</remarks>
         public dynamic Content(params object[] ids)
         {
             return ContentForObjects(ids);
@@ -749,55 +794,53 @@ namespace Umbraco.Web
         }
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
         public dynamic Content(params int[] ids)
 		{
             return ContentQuery.Content(ids);
 		}
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers, or the keys, of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
+        /// <remarks>Does not support mixing identifiers and keys.</remarks>
         public dynamic Content(params string[] ids)
 		{
             return ContentForObjects(ids);
         }
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers, or the keys, of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
+        /// <remarks>Does not support mixing identifiers and keys.</remarks>
         public dynamic Content(IEnumerable<object> ids)
 		{
             return ContentForObjects(ids);
         }
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
         public dynamic Content(IEnumerable<int> ids)
 		{
             return ContentQuery.Content(ids);
 		}
 
         /// <summary>
-        /// Gets the contents corresponding to the identifiers.
+        /// Gets content items from the cache.
         /// </summary>
-        /// <param name="ids">The content identifiers.</param>
-        /// <returns>The existing contents corresponding to the identifiers.</returns>
-        /// <remarks>If an identifier does not match an existing content, it will be missing in the returned value.</remarks>
+        /// <param name="ids">The unique identifiers, or the keys, of the content items.</param>
+        /// <returns>The content items that were found in the cache.</returns>
+        /// <remarks>Does not support mixing identifiers and keys.</remarks>
         public dynamic Content(IEnumerable<string> ids)
 		{
             return ContentForObjects(ids);
@@ -824,7 +867,7 @@ namespace Umbraco.Web
             if (s != null)
             {
                 return int.TryParse(s, out intId);
-            }               
+            }
             if (id is int)
             {
                 intId = (int) id;
@@ -892,7 +935,7 @@ namespace Umbraco.Web
 		/// <param name="id"></param>
 		/// <returns></returns>
 		/// <remarks>
-		/// We accept an object type because GetPropertyValue now returns an 'object', we still want to allow people to pass 
+		/// We accept an object type because GetPropertyValue now returns an 'object', we still want to allow people to pass
 		/// this result in to this method.
 		/// This method will throw an exception if the value is not of type int or string.
 		/// </remarks>
@@ -1097,7 +1140,7 @@ namespace Umbraco.Web
         }
 
 		#endregion
-        
+
 		#region Search
 
 		/// <summary>
@@ -1344,7 +1387,7 @@ namespace Umbraco.Web
         #endregion
 
         #region canvasdesigner
-        
+
         [Obsolete("Use EnableCanvasDesigner on the HtmlHelper extensions instead")]
         public IHtmlString EnableCanvasDesigner()
         {