Default is HTTP/1.1; updated documentation

DecaTec · Jul 21, 2017 · 62580b3 · 62580b3
1 parent e9b842a
commit 62580b3
Show file tree

Hide file tree

Showing 12 changed files with 92 additions and 20 deletions.
diff --git a/DecaTec.WebDav/WebDavArtifacts/Prop.cs b/DecaTec.WebDav/WebDavArtifacts/Prop.cs
@@ -826,7 +826,9 @@ public string ParentName
         /// <summary>
         /// Gets or sets additional WebDAV properties as <see cref="XElement"/> array.
         /// </summary>
-        /// <remarks>This property is used for WebDAV properties not defined in <see href="https://www.ietf.org/rfc/rfc4918.txt">RFC 4918</see>, <see href="https://tools.ietf.org/html/rfc4331">RFC 4331</see>, <see href="https://tools.ietf.org/html/draft-hopmann-collection-props-00">Additional WebDAV Collection Properties</see> or IIS WebDAV specification.</remarks>
+        /// <remarks>This property is used for WebDAV properties not defined in <see href="https://www.ietf.org/rfc/rfc4918.txt">RFC 4918</see>, <see href="https://tools.ietf.org/html/rfc4331">RFC 4331</see>, <see href="https://tools.ietf.org/html/draft-hopmann-collection-props-00">Additional WebDAV Collection Properties</see> or IIS WebDAV specification.
+        /// <br /><br />
+        /// Important: Additional WebDAV properties are currently not supported on Xamarin. See <see href="https://github.com/DecaTec/Portable-WebDAV-Library/wiki/Xamarin">the project's wiki</see> for more information about the Portable WebDAV Library used on Xamarin.</remarks>
         [XmlAnyElement]
         public XElement[] AdditionalProperties
         {

diff --git a/DecaTec.WebDav/WebDavClient.cs b/DecaTec.WebDav/WebDavClient.cs
@@ -114,7 +114,7 @@ public class WebDavClient : HttpClient
 
         private const string MediaTypeXml = "application/xml";
 
-        internal static readonly Version DefaultHttpVersion = new Version(2, 0);
+        internal static readonly Version DefaultHttpVersion = new Version(1, 1);
 
         #region Constructor
 

diff --git a/DecaTec.WebDav/WebDavSessionItem.cs b/DecaTec.WebDav/WebDavSessionItem.cs
@@ -615,6 +615,7 @@ private set
         /// <summary>
         /// Gets the <see cref="AdditionalWebDavProperties"/> representing the additional WebDAV properties not defined in <see href="https://www.ietf.org/rfc/rfc4918.txt">RFC 4918</see>, <see href="https://tools.ietf.org/html/rfc4331">RFC 4331</see>, <see href="https://tools.ietf.org/html/draft-hopmann-collection-props-00">Additional WebDAV Collection Properties</see> or the IIS WebDAV specification.
         /// </summary>
+        /// <remarks>Important: Additional WebDAV properties are currently not supported on Xamarin. See <see href="https://github.com/DecaTec/Portable-WebDAV-Library/wiki/Xamarin">the project's wiki</see> for more information about the Portable WebDAV Library used on Xamarin.</remarks>
         public AdditionalWebDavProperties AdditionalProperties
         {
             get

diff --git a/Documentation/DecaTec.WebDav.Documentation/Content/HowTos/HowTo.aml b/Documentation/DecaTec.WebDav.Documentation/Content/HowTos/HowTo.aml
@@ -30,6 +30,12 @@
             </para>
           </listItem>
 
+          <listItem>
+            <para>
+              <link xlink:href="f451c65c-190c-4e25-af1e-b7d2e6cb24cb" />
+            </para>
+          </listItem>
+
           <listItem>
             <para>
               <link xlink:href="3023122f-9dd2-4d7e-83b9-50db4c2fe2b3" />

diff --git a/Documentation/DecaTec.WebDav.Documentation/Content/HowTos/Http2.aml b/Documentation/DecaTec.WebDav.Documentation/Content/HowTos/Http2.aml
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="f451c65c-190c-4e25-af1e-b7d2e6cb24cb" revisionNumber="1">
+  <developerConceptualDocument
+    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+
+    <introduction>
+      <para>
+        The Portable WebDAV Library has full HTTP/2 support. But for compatibility reasons (Xamarin), the default is still HTTP/1.1.
+      </para>
+    </introduction>
+
+    <section>
+      <content>
+        <para>
+          In oder to use HTTP/2, use the property HttpVersion or an overloaded constructor of WebDavClient/WebDavSession:
+        </para>
+        <code language="c#">
+          <![CDATA[
+public async Task<IList<WebDavSessionItem>> List()
+{
+    // The base URL of the WebDAV server.
+    var webDavServerUrl = @"http://www.myserver.com/webdav/";
+
+    // Specify the user credentials and use it to create a WebDavSession instance.
+    var credentials = new NetworkCredential("MyUsername", "MyPassword");
+
+    using (var webDavSession = new WebDavSession(webDavServerUrl, credentials, new Version(2, 0)))
+    {
+        // You could also use the property HttpVersion to use HTTP/2:
+        // webDavSession.HttpVersion = new Version(2, 0);
+
+        var list = await webDavSession.ListAsync("/");
+        return list;
+    }
+}
+          ]]>
+        </code>
+      </content>
+    </section>
+
+    <relatedTopics>
+      <link xlink:href="6eaaa932-6e58-4f05-82be-6bb1a0403612" />
+    </relatedTopics>
+
+  </developerConceptualDocument>
+</topic>
diff --git a/Documentation/DecaTec.WebDav.Documentation/Content/HowTos/Xamarin.aml b/Documentation/DecaTec.WebDav.Documentation/Content/HowTos/Xamarin.aml
@@ -55,6 +55,20 @@ var items = await webDavSession.ListAsync("/folder"); // Will raise exception
       </content>
     </section>
 
+    <section>
+      <title>
+        Unknown WebDAV properties
+      </title>
+      <content>
+        <para>
+          Currently unknown WebDAV properties are not supported when using the Portable WebDAV Library on Xamarin. This is due to the fact that these AdditionalProperties of Prop cannot be (de-) serialized on Xamarin. The operations will throw an exception that the XmlAnyElementAttribute cannot be applied to XElement arrays.
+        </para>
+        <para>
+          As a workaround, use WebDavClient providing XML strings directly (e.g. for PropFind). These XML strings need to be created by the client using the library.
+        </para>
+      </content>
+    </section>
+
     <relatedTopics>
       <link xlink:href="6eaaa932-6e58-4f05-82be-6bb1a0403612" />
     </relatedTopics>

diff --git a/Documentation/DecaTec.WebDav.Documentation/Content/VersionHistory/v1.1.0.0.aml b/Documentation/DecaTec.WebDav.Documentation/Content/VersionHistory/v1.1.0.0.aml
@@ -13,13 +13,11 @@
 
           <listItem>
             <para>
-              Added full HTTP/2 support.
+              Added full HTTP/2 support. 
             </para>
-          </listItem>
-
-          <listItem>
+
             <para>
-              The library now uses HTTP/2 by default. Use the overloaded constructors (WebDavClient/WebDavSession) to use other HTTP versions than 2.0.
+              The default HTTP version is still HTTP/1.1 for compatibility reasons (Xamarin). Use the overloaded constructors or the property HttpVersion (WebDavClient/WebDavSession) to use HTTP/2 instead.
             </para>
           </listItem>
 

diff --git a/Documentation/DecaTec.WebDav.Documentation/ContentLayout.content b/Documentation/DecaTec.WebDav.Documentation/ContentLayout.content
@@ -24,7 +24,12 @@
         <HelpKeyword index="K" term="app capabilities, UWP" />
       </HelpKeywords>
     </Topic>
-    <Topic id="3023122f-9dd2-4d7e-83b9-50db4c2fe2b3" visible="True" title="Unknown WebDAV properties" linkText="Unknown WebDAV properties">
+    <Topic id="f451c65c-190c-4e25-af1e-b7d2e6cb24cb" visible="True" title="HTTP/2" linkText="HTTP/2">
+      <HelpKeywords>
+        <HelpKeyword index="K" term="HTTP/2" />
+      </HelpKeywords>
+    </Topic>
+    <Topic id="3023122f-9dd2-4d7e-83b9-50db4c2fe2b3" visible="True" isSelected="true" title="Unknown WebDAV properties" linkText="Unknown WebDAV properties">
       <HelpKeywords>
         <HelpKeyword index="K" term="unknown webdav properties" />
       </HelpKeywords>
@@ -144,7 +149,7 @@
         <HelpKeyword index="K" term="version, 1.0.1.0" />
       </HelpKeywords>
     </Topic>
-    <Topic id="84c16af9-768f-4ca6-9887-751edce44079" visible="True" isSelected="true" title="Version 1.1.0.0" linkText="Version 1.1.0.0">
+    <Topic id="84c16af9-768f-4ca6-9887-751edce44079" visible="True" title="Version 1.1.0.0" linkText="Version 1.1.0.0">
       <HelpKeywords>
         <HelpKeyword index="K" term="version, 1.1.0.0" />
       </HelpKeywords>

diff --git a/Documentation/DecaTec.WebDav.Documentation/DecaTec.WebDav.Documentation.shfbproj b/Documentation/DecaTec.WebDav.Documentation/DecaTec.WebDav.Documentation.shfbproj
@@ -92,6 +92,7 @@
   <ItemGroup>
     <None Include="Content\HowTos\AppCapabilities.aml" />
     <None Include="Content\HowTos\HowTo.aml" />
+    <None Include="Content\HowTos\Http2.aml" />
     <None Include="Content\HowTos\UnknownProperties.aml" />
     <None Include="Content\HowTos\UntrustedSSL.aml" />
     <None Include="Content\HowTos\UploadDownloadWithProgress.aml" />

diff --git a/UnitTests/DecaTec.WebDav.UnitTest/UnitTestWebDavClient.cs b/UnitTests/DecaTec.WebDav.UnitTest/UnitTestWebDavClient.cs
@@ -61,14 +61,14 @@ private WebDavClient CreateWebDavClient(MockHttpMessageHandler mockHandler)
         public void UT_WebDavClient_ConstructorWithDefaultHttpVersion()
         {
             var client = new WebDavClient();
-            Assert.AreEqual(new Version(2, 0), client.HttpVersion);
+            Assert.AreEqual(new Version(1, 1), client.HttpVersion);
         }
 
         [TestMethod]
         public void UT_WebDavClient_ConstructorWithNonDefaultHttpVersion()
         {
-            var client = new WebDavClient(new Version(1, 1));
-            Assert.AreEqual(new Version(1, 1), client.HttpVersion);
+            var client = new WebDavClient(new Version(2, 0));
+            Assert.AreEqual(new Version(2, 0), client.HttpVersion);
         }
 
         #endregion Constructor
@@ -147,7 +147,7 @@ public void UT_WebDavClient_UnLockAsync_WithoutLockToken()
         public void UT_WebDavClient_WithHttpVersionDefault()
         {
             var mockHandler = new MockHttpMessageHandler();
-            var defaultHttpVersion = new Version(2, 0);
+            var defaultHttpVersion = new Version(1, 1);
 
             mockHandler.When(WebDavMethod.PropFind, WebDavRootFolder).With(req => req.Version == defaultHttpVersion).Respond(HttpStatusCode.OK);
 

diff --git a/UnitTests/DecaTec.WebDav.UnitTest/UnitTestWebDavSession.cs b/UnitTests/DecaTec.WebDav.UnitTest/UnitTestWebDavSession.cs
@@ -1,15 +1,13 @@
 using DecaTec.WebDav.Headers;
 using DecaTec.WebDav.MessageHandlers;
 using DecaTec.WebDav.Tools;
-using DecaTec.WebDav.WebDavArtifacts;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 using RichardSzalay.MockHttp;
 using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Net;
 using System.Net.Http;
-using System.Text;
 
 namespace DecaTec.WebDav.UnitTest
 {
@@ -65,16 +63,16 @@ public void UT_WebDavSession_ConstructorWithDefaultHttpVersion()
         {
             var credentials = new NetworkCredential(UserName, Password);
             var session = new WebDavSession(credentials);
-            Assert.AreEqual(new Version(2, 0), session.HttpVersion);
+            Assert.AreEqual(new Version(1, 1), session.HttpVersion);
         }
 
 
         [TestMethod]
         public void UT_WebDavSession_ConstructorWithNomDefaultHttpVersion()
         {
             var credentials = new NetworkCredential(UserName, Password);
-            var session = new WebDavSession(credentials, new Version(1, 1));
-            Assert.AreEqual(new Version(1, 1), session.HttpVersion);
+            var session = new WebDavSession(credentials, new Version(2, 0));
+            Assert.AreEqual(new Version(2, 0), session.HttpVersion);
         }
 
 

diff --git a/changelog.md b/changelog.md
@@ -1,6 +1,6 @@
 v1.1.0.0
-- Added full HTTP/2 support.
-- The library now uses HTTP/2 by default. Use the overloaded constructors (WebDavClient/WebDavSession) to use other HTTP versions than 2.0.
+- Added full HTTP/2 support. The default HTTP version is still HTTP/1.1 for compatibility reasons (Xamarin). Use the overloaded constructors or the property HttpVersion (WebDavClient/WebDavSession) to use HTTP/2 instead.
+- The WebDavSession now exposes the DefaultRequestHeaders of the underlying WebDavClient. By using this property, default headers can be set which should be sent with every request of the WebDavSession.
 
 v1.0.1.0
 - Bugfix [Xamarin]: WebDavSession.ListAsync returned wrong URLs when used with folders containing spaces.