/// <summary>
        /// Return the media object for the specified <paramref name="mediaObjectId" />, optionally including the metadata
        /// for each item. Returns null if no matching object is found in the data store.
        /// </summary>
        /// <param name="mediaObjectId">The ID that uniquely identifies the desired media object.</param>
        /// <param name="includeMetadata">When <c>true</c> include metadata items on the
        /// <see cref="MediaObjectDto.MediaObjectMetadata" /> property. When <c>false</c>, the property is null.</param>
        /// <returns>Returns an instance of <see cref="MediaObjectDto" />, or null if no matching object is found.</returns>
        public static MediaObjectDto GetMediaObjectById(int mediaObjectId, bool includeMetadata)
        {
            MediaObjectDto moDto = null;

            using (SqlConnection cn = SqlDataProvider.GetDbConnection())
            {
                using (IDataReader dr = GetCommandMediaObjectSelectById(mediaObjectId, cn).ExecuteReader(CommandBehavior.SingleRow))
                {
                    while (dr.Read())
                    {
                        // SQL:
                        //SELECT
                        //  MediaObjectId, FKAlbumId, Title, HashKey, ThumbnailFilename, ThumbnailWidth, ThumbnailHeight,
                        //  ThumbnailSizeKB, OptimizedFilename, OptimizedWidth, OptimizedHeight, OptimizedSizeKB,
                        //  OriginalFilename, OriginalWidth, OriginalHeight, OriginalSizeKB, ExternalHtmlSource, ExternalType, Seq,
                        //  CreatedBy, DateAdded, LastModifiedBy, DateLastModified, IsPrivate
                        //FROM [gs_MediaObject]
                        //WHERE MediaObjectId = @MediaObjectId
                        moDto = new MediaObjectDto
                        {
                            MediaObjectId      = dr.GetInt32(0),
                            FKAlbumId          = dr.GetInt32(1),
                            Title              = dr.GetString(2),
                            HashKey            = dr.GetString(3),
                            ThumbnailFilename  = dr.GetString(4),
                            ThumbnailWidth     = dr.GetInt32(5),
                            ThumbnailHeight    = dr.GetInt32(6),
                            ThumbnailSizeKB    = dr.GetInt32(7),
                            OptimizedFilename  = dr.GetString(8),
                            OptimizedWidth     = dr.GetInt32(9),
                            OptimizedHeight    = dr.GetInt32(10),
                            OptimizedSizeKB    = dr.GetInt32(11),
                            OriginalFilename   = dr.GetString(12),
                            OriginalWidth      = dr.GetInt32(13),
                            OriginalHeight     = dr.GetInt32(14),
                            OriginalSizeKB     = dr.GetInt32(15),
                            ExternalHtmlSource = dr.GetString(16),
                            ExternalType       = dr.GetString(17),
                            Seq              = dr.GetInt32(18),
                            CreatedBy        = dr.GetString(19),
                            DateAdded        = dr.GetDateTime(20),
                            LastModifiedBy   = dr.GetString(21),
                            DateLastModified = dr.GetDateTime(22),
                            IsPrivate        = dr.GetBoolean(23)
                        };
                    }
                }

                if (includeMetadata && (moDto != null))
                {
                    moDto.MediaObjectMetadata = new HashSet <MediaObjectMetadataDto>(MediaObject.GetMetadataItemsByMediaObjectId(moDto.MediaObjectId, cn));
                }
            }

            return(moDto);
        }
        /// <summary>
        /// Persist the specified media object to the data store. Return the ID of the media object.
        /// </summary>
        /// <param name="mediaObject">An instance of <see cref="IGalleryObject"/> to persist to the data store.</param>
        /// <returns>
        /// Return the ID of the media object. If this is a new media object and a new ID has been
        /// assigned, then this value has also been assigned to the ID property of the object.
        /// </returns>
        /// <exception cref="ArgumentNullException">Thrown when <paramref name="mediaObject" /> is null.</exception>
        public override int MediaObject_Save(IGalleryObject mediaObject)
        {
            if (mediaObject == null)
                throw new ArgumentNullException("mediaObject");

            using (GspContext ctx = new GspContext())
            {
                if (mediaObject.IsNew)
                {
                    MediaObjectDto moDto = new MediaObjectDto
                                                                    {
                                                                        HashKey = mediaObject.Hashkey,
                                                                        FKAlbumId = mediaObject.Parent.Id,
                                                                        ThumbnailFilename = mediaObject.Thumbnail.FileName,
                                                                        ThumbnailWidth = mediaObject.Thumbnail.Width,
                                                                        ThumbnailHeight = mediaObject.Thumbnail.Height,
                                                                        ThumbnailSizeKB = mediaObject.Thumbnail.FileSizeKB,
                                                                        OptimizedFilename = mediaObject.Optimized.FileName,
                                                                        OptimizedWidth = mediaObject.Optimized.Width,
                                                                        OptimizedHeight = mediaObject.Optimized.Height,
                                                                        OptimizedSizeKB = mediaObject.Optimized.FileSizeKB,
                                                                        OriginalFilename = mediaObject.Original.FileName,
                                                                        OriginalWidth = mediaObject.Original.Width,
                                                                        OriginalHeight = mediaObject.Original.Height,
                                                                        OriginalSizeKB = mediaObject.Original.FileSizeKB,
                                                                        ExternalHtmlSource = mediaObject.Original.ExternalHtmlSource,
                                                                        ExternalType = (mediaObject.Original.ExternalType == MimeTypeCategory.NotSet ? String.Empty : mediaObject.Original.ExternalType.ToString()),
                                                                        Title = mediaObject.Title,
                                                                        Seq = mediaObject.Sequence,
                                                                        CreatedBy = mediaObject.CreatedByUserName,
                                                                        DateAdded = mediaObject.DateAdded,
                                                                        LastModifiedBy = mediaObject.LastModifiedByUserName,
                                                                        DateLastModified = mediaObject.DateLastModified,
                                                                        IsPrivate = mediaObject.IsPrivate
                                                                    };

                    ctx.MediaObjects.Add(moDto);
                    ctx.SaveChanges(); // Save now so we can get at the ID

                    if (mediaObject.Id != moDto.MediaObjectId)
                        mediaObject.Id = moDto.MediaObjectId;

                    // Insert metadata items, if any, into MediaObjectMetadata table.
                    InsertMetadataItems(mediaObject, ctx);
                }
                else
                {
                    MediaObjectDto moDto = ctx.MediaObjects.Find(mediaObject.Id);

                    if (moDto != null)
                    {
                        moDto.HashKey = mediaObject.Hashkey;
                        moDto.FKAlbumId = mediaObject.Parent.Id;
                        moDto.ThumbnailFilename = mediaObject.Thumbnail.FileName;
                        moDto.ThumbnailWidth = mediaObject.Thumbnail.Width;
                        moDto.ThumbnailHeight = mediaObject.Thumbnail.Height;
                        moDto.ThumbnailSizeKB = mediaObject.Thumbnail.FileSizeKB;
                        moDto.OptimizedFilename = mediaObject.Optimized.FileName;
                        moDto.OptimizedWidth = mediaObject.Optimized.Width;
                        moDto.OptimizedHeight = mediaObject.Optimized.Height;
                        moDto.OptimizedSizeKB = mediaObject.Optimized.FileSizeKB;
                        moDto.OriginalFilename = mediaObject.Original.FileName;
                        moDto.OriginalWidth = mediaObject.Original.Width;
                        moDto.OriginalHeight = mediaObject.Original.Height;
                        moDto.OriginalSizeKB = mediaObject.Original.FileSizeKB;
                        moDto.ExternalHtmlSource = mediaObject.Original.ExternalHtmlSource;
                        moDto.ExternalType = (mediaObject.Original.ExternalType == MimeTypeCategory.NotSet ? String.Empty : mediaObject.Original.ExternalType.ToString());
                        moDto.Title = mediaObject.Title;
                        moDto.Seq = mediaObject.Sequence;
                        moDto.CreatedBy = mediaObject.CreatedByUserName;
                        moDto.DateAdded = mediaObject.DateAdded;
                        moDto.LastModifiedBy = mediaObject.LastModifiedByUserName;
                        moDto.DateLastModified = mediaObject.DateLastModified;
                        moDto.IsPrivate = mediaObject.IsPrivate;

                        // Update metadata items, if necessary, in MediaObjectMetadata table.
                        UpdateMetadataItems(mediaObject, ctx);
                    }
                }

                ctx.SaveChanges();
            }

            return mediaObject.Id;
        }
        /// <summary>
        /// Return the media object for the specified <paramref name="mediaObjectId" />, optionally including the metadata 
        /// for each item. Returns null if no matching object is found in the data store.
        /// </summary>
        /// <param name="mediaObjectId">The ID that uniquely identifies the desired media object.</param>
        /// <param name="includeMetadata">When <c>true</c> include metadata items on the 
        /// <see cref="MediaObjectDto.MediaObjectMetadata" /> property. When <c>false</c>, the property is null.</param>
        /// <returns>Returns an instance of <see cref="MediaObjectDto" />, or null if no matching object is found.</returns>
        public static MediaObjectDto GetMediaObjectById(int mediaObjectId, bool includeMetadata)
        {
            MediaObjectDto moDto = null;
            using (SqlConnection cn = SqlDataProvider.GetDbConnection())
            {
                using (IDataReader dr = GetCommandMediaObjectSelectById(mediaObjectId, cn).ExecuteReader(CommandBehavior.SingleRow))
                {
                    while (dr.Read())
                    {
                        // SQL:
                        //SELECT
                        //  MediaObjectId, FKAlbumId, Title, HashKey, ThumbnailFilename, ThumbnailWidth, ThumbnailHeight,
                        //  ThumbnailSizeKB, OptimizedFilename, OptimizedWidth, OptimizedHeight, OptimizedSizeKB,
                        //  OriginalFilename, OriginalWidth, OriginalHeight, OriginalSizeKB, ExternalHtmlSource, ExternalType, Seq,
                        //  CreatedBy, DateAdded, LastModifiedBy, DateLastModified, IsPrivate
                        //FROM [gs_MediaObject]
                        //WHERE MediaObjectId = @MediaObjectId
                        moDto = new MediaObjectDto
                        {
                            MediaObjectId = dr.GetInt32(0),
                            FKAlbumId = dr.GetInt32(1),
                            Title = dr.GetString(2),
                            HashKey = dr.GetString(3),
                            ThumbnailFilename = dr.GetString(4),
                            ThumbnailWidth = dr.GetInt32(5),
                            ThumbnailHeight = dr.GetInt32(6),
                            ThumbnailSizeKB = dr.GetInt32(7),
                            OptimizedFilename = dr.GetString(8),
                            OptimizedWidth = dr.GetInt32(9),
                            OptimizedHeight = dr.GetInt32(10),
                            OptimizedSizeKB = dr.GetInt32(11),
                            OriginalFilename = dr.GetString(12),
                            OriginalWidth = dr.GetInt32(13),
                            OriginalHeight = dr.GetInt32(14),
                            OriginalSizeKB = dr.GetInt32(15),
                            ExternalHtmlSource = dr.GetString(16),
                            ExternalType = dr.GetString(17),
                            Seq = dr.GetInt32(18),
                            CreatedBy = dr.GetString(19),
                            DateAdded = dr.GetDateTime(20),
                            LastModifiedBy = dr.GetString(21),
                            DateLastModified = dr.GetDateTime(22),
                            IsPrivate = dr.GetBoolean(23)
                        };
                    }
                }

                if (includeMetadata && (moDto != null))
                {
                    moDto.MediaObjectMetadata = new HashSet<MediaObjectMetadataDto>(MediaObject.GetMetadataItemsByMediaObjectId(moDto.MediaObjectId, cn));
                }
            }

            return moDto;
        }