📝 Upgrading from RC2 to RTM

docs/miscellaneous/index.rst

@@ -10,5 +10,6 @@ Miscellaneous
     testing
     configuring-dbcontext
     rc1-rc2-upgrade
+    rc2-rtm-upgrade
     cli/index
     internals/index

docs/miscellaneous/rc2-rtm-upgrade.rst

@@ -0,0 +1,88 @@
+Upgrading from RC2 to RTM
+=========================
+
+This article provides guidance for moving an application built with the RC2 packages to 1.0.0 RTM.
+
+.. contents:: `In this article:`
+    :local:
+
+Package Versions
+----------------
+
+The names of the top level packages that you would typically install into an application did not change between RC2 and RTM.
+
+You need to upgrade the installed packages to the RTM versions:
+  * Runtime packages (e.g. ``Microsoft.EntityFrameworkCore.SqlServer``) changed from ``1.0.0-rc2-final`` to ``1.0.0``.
+  * The ``Microsoft.EntityFrameworkCore.Tools`` package changed from ``1.0.0-preview1-final`` to ``1.0.0-preview2-final``. Note that tooling is still pre-release.
+
+Existing migrations may need maxLength added
+--------------------------------------------
+
+In RC2, the column definition in a migration looked like ``table.Column<string>(nullable: true)``` and the length of the column was looked up in some metadata we store in the code behind the migration. In RTM, the length is now included in the scaffolded code ``table.Column<string>(maxLength: 450, nullable: true)``.
+
+Any existing migrations that were scaffolded prior to using RTM will not have the ``maxLength`` argument specified. This means the maximum length supported by the database will be used (``nvarchar(max)`` on SQL Server). This may be fine for some columns, but columns that are part of a key, foreign key, or index need to be updated to include a maximum length. By convention, 450 is the maximum length used for keys, foreign keys, and indexed columns. If you have explicitly configured a length in the model, then you should use that length instead.
+
+**ASP.NET Identity**
+
+This change impacts projects that use ASP.NET Identity and were created from a pre-RTM project template. The project template includes a migration used to create the database. This migration must be edited to specify a maximum length of ``256`` for the following columns.
+
+    * AspNetRoles
+        * Name
+        * NormalizedName
+    * AspNetUsers
+        * Email
+        * NormalizedEmail
+        * NormalizedUserName
+        * UserName
+
+Failure to make this change will result in the following exception when the initial migration is applied to a database.
+
+    System.Data.SqlClient.SqlException (0x80131904): Column 'NormalizedName' in table 'AspNetRoles' is of a type that is invalid for use as a key column in an index. .
+
+
+.NET Core: Remove "imports" in project.json
+-------------------------------------------
+
+If you were targeting .NET Core with RC2, you needed to add ``imports`` to project.json as a temporary workaround for some of EF Core's dependencies not supporting .NET Standard. These can now be removed.
+
+.. code-block:: json
+    :emphasize-lines: 4
+
+    {
+      "frameworks": {
+        "netcoreapp1.0": {
+          "imports": ["dnxcore50", "portable-net451+win8"]
+        }
+    }
+
+UWP: Add binding redirects
+--------------------------
+
+Attempting to run EF commands on Universal Windows Platform (UWP) projects results in the following error:
+
+    System.IO.FileLoadException: Could not load file or assembly 'System.IO.FileSystem.Primitives, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference.
+
+You need to manually add binding redirects to the UWP project. Create a file named ``App.config`` in the project root folder and add redirects to the correct assembly versions.
+
+.. code-block:: xml
+
+    <configuration>
+     <runtime>
+       <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
+         <dependentAssembly>
+           <assemblyIdentity name="System.IO.FileSystem.Primitives"
+                             publicKeyToken="b03f5f7f11d50a3a"
+                             culture="neutral" />
+           <bindingRedirect oldVersion="4.0.0.0"
+                            newVersion="4.0.1.0"/>
+         </dependentAssembly>
+         <dependentAssembly>
+           <assemblyIdentity name="System.Threading.Overlapped"
+                             publicKeyToken="b03f5f7f11d50a3a"
+                             culture="neutral" />
+           <bindingRedirect oldVersion="4.0.0.0"
+                            newVersion="4.0.1.0"/>
+         </dependentAssembly>
+       </assemblyBinding>
+     </runtime>
+    </configuration>