Skip to content

Commit 63652ff

Browse files
mythzmythz
committed
Add v4.5.0 Release Notes
1 parent 0f07f1b commit 63652ff

File tree

1 file changed

+344
-0
lines changed

1 file changed

+344
-0
lines changed

‎docs/2016/v4.5.0.md

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
# v4.5.0 Release Notes
2+
3+
The major change in this release and the reason for the major version number change is that **all** packages
4+
have been **upgraded to .NET 4.5** as
5+
[announced earlier this year](https://github.com/ServiceStack/ServiceStack/blob/master/docs/2016/v4.0.54.md#warning-net-40-builds-will-cease-after-august-1-2016).
6+
If your ServiceStack projects are already on .NET 4.5 this will be a seamless update just like any other
7+
release except it will install **.NET 4.5** ServiceStack .dlls instead of the previous **.NET 4.0** dlls.
8+
9+
If your ServiceStack projects are instead on .NET 4.0 this will be a breaking change which will require
10+
converting **all** your projects to **.NET 4.5 Framework** before upgrading, e.g:
11+
12+
![](http://i.imgur.com/GV8TmAS.png)
13+
14+
You will also need to have .NET 4.5 Framework installed on your deployment Servers if it doesn't have it already.
15+
16+
### Upgraded 3rd Party NuGet packages
17+
18+
All external NuGet package dependencies have also been upgraded to use the **latest .NET 4.5 dlls**, including
19+
using **v3.1.7** of `Npgsql`, **v3.6.5** of `RabbitMQ.Client` and `ServiceStack.Razor` is now referencing
20+
**v3.2.3** of the official `Microsoft.AspNet.Razor` NuGet package. We've also upgraded our build servers and
21+
all core ServiceStack projects to start using C# 6 which we're able to immediately benefit from by replacing
22+
lots of C# 5 boilerplate with C# 6 syntax sugar, we've also updated embedded version of Dapper to the latest
23+
version which is a heavy user of C# 6 features.
24+
25+
We've intentionally kept features to the core packages in this release minimal so should any issues arise in
26+
this release can be attributable to the upgrade to .NET 4.5.
27+
28+
## [.NET Core support for ServiceStack.Redis!](https://github.com/ServiceStack/ServiceStack.Redis/blob/netcore/docs/pages/netcore.md)
29+
30+
In following the
31+
[.NET Core support of our Text and Client libraries](https://github.com/ServiceStack/ServiceStack/blob/master/docs/2016/v4.0.62.md#net-core-support-for-servicestackclient)
32+
in our last release we've extended our support for .NET Core in this release to now also include
33+
[ServiceStack.Redis](https://github.com/ServiceStack/ServiceStack.Redis)
34+
where we now have .NET Core builds for our [Top 3 popular NuGet packages](https://www.nuget.org/profiles/servicestack).
35+
36+
Just like the other .NET Core libraries .NET Core builds of ServiceStack.Redis is released with a `*.Core`
37+
suffix until development of .NET Core has stabilized, i.e:
38+
39+
PM> Install-Package ServiceStack.Redis.Core
40+
41+
To make it easy to start using Redis in a .NET Core App we've created a step-by-step guide for
42+
[getting started with ServiceStack.Redis on .NET Core](https://github.com/ServiceStack/ServiceStack.Redis/blob/netcore/docs/pages/netcore.md)
43+
in both Windows and Linux.
44+
45+
## [New Xamarin.Forms TechStacks App](https://github.com/ServiceStackApps/TechStacksXamarin)
46+
47+
We've added a new TechStacks Mobile App to our ever increasing showcase of different ways where ServiceStack
48+
provides a seamless end-to-end Typed API development experience for developing Native Mobile Apps which now includes:
49+
50+
- [C# iOS/Android Xamarin.Forms TechStacks App](https://github.com/ServiceStackApps/TechStacksXamarin) - **new!**
51+
- [Swift iOS TechStacks App](https://github.com/ServiceStackApps/TechStacksApp)
52+
- [Java Android Techstacks App](https://github.com/ServiceStackApps/TechStacksAndroidApp)
53+
- [Kotlin Android TechStacks App](https://github.com/ServiceStackApps/TechStacksKotlinApp)
54+
- [C# Xamarin.Android TechStacks Auth Example](https://github.com/ServiceStackApps/TechStacksAuth)
55+
56+
Whilst not as flexibile or performant as native code, [Xamarin.Forms](https://www.xamarin.com/forms) enables
57+
the most code reuse of all the available options when needing to develop both iOS and Android Apps whilst
58+
still allowing for customization through styling or custom platform specific renderers. It also benefits from being
59+
able to use C# and much of the rich cross-platform libraries in .NET.
60+
61+
Despite sharing the majority of UI code between Android and iOS, Xamarin.Forms Apps also adopt the navigation
62+
idioms of each platform to provide a native "look and feel" which we can see by running the
63+
TechStacks Xamarin.Forms App on iOS and Android:
64+
65+
[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/TechStacksXamForms/video_preview.png)](https://www.youtube.com/watch?v=4ghchU3xKs4)
66+
67+
See the [TechStacksXamarin](https://github.com/ServiceStackApps/TechStacksXamarin) Github project for more info
68+
on creating Xamarin.Forms Apps and how it leverages
69+
[Add ServiceStack Reference](https://github.com/ServiceStack/ServiceStack/wiki/Add-ServiceStack-Reference) and
70+
ServiceStack's [.NET Service Clients](https://github.com/ServiceStack/ServiceStack/wiki/C%23-client)
71+
to enable a responsive and productive development experience.
72+
73+
## [AutoQuery Viewer](https://github.com/ServiceStack/Admin) Saved Queries
74+
75+
We've further refined [AutoQuery Viewer](https://github.com/ServiceStack/Admin) and added support for
76+
Saved Queries where you can save queries under each AutoQuery Service by clicking the **save icon**.
77+
78+
The saved query will be listed with the name provided and displayed to the right of the save icon, e.g:
79+
80+
[![](http://i.imgur.com/hySw1T9.png)](https://github.com/ServiceStack/Admin)
81+
82+
This makes it easy for everyone to maintain and easily switch between multiple personalized views
83+
of any dataset.
84+
85+
## Create Live Executable Docs with Gistlyn
86+
87+
In our mission to make [Gistlyn](http://gistlyn.com) an immensely useful and collaborative learning tool for
88+
exploring any .NET library, we've greatly improved the UX for editing Collections making it easier than ever to
89+
create "Live documentation" which we believe is the best way to learn about a library, mixing documentation and
90+
providing a live development experience letting developers try out and explore what they've just learned without
91+
losing context by needing to switch to their development environment and setup new projects to match each code sample.
92+
Gistlyn also makes it easy to share C# snippets with colleagues or library authors with just a URL or a saved
93+
Gist ID which anyone can view in a browser at [gistlyn.com](http://gistlyn.com) or on their
94+
[Desktop version of Gistlyn](http://gistlyn.com/downloads).
95+
96+
Here's an example of the new editing Collection features in action:
97+
98+
[![](http://i.imgur.com/156wYPJ.png)](https://youtu.be/FkdzYsx2lYw)
99+
100+
These new UX improvements have closed the loop in Gistlyn which lets you create, edit, browse and run C# Gists or
101+
Markdown docs, all without leaving Gistlyn. The editing experience is seamless and retains the same benefits
102+
as editing C# gists, including auto-saving as-you-type to localStorage, integrated persistence to Github gists,
103+
snapshots, deep linking as well as a built-in **Markdown Editor** with **Live Preview**, **easy linking** and
104+
**seamless image uploads** making it a great for authoring any kind of Markdown documentation and what we used
105+
to create these Release Notes :)
106+
107+
Creating a Collection can be done at anytime from Gistlyn's main menu:
108+
109+
![](http://i.imgur.com/UVbKOWn.png)
110+
111+
This will open a new Markdown Document into Gistlyn's built-in **Markdown Editor**. Hit `Ctrl+S` to save your
112+
modified copy to [your Github Gists](gist.github.com). After saving, the top bar will turn **Green** to indicate
113+
you're viewing or modifying one of your own Gists or Collections:
114+
115+
![](http://i.imgur.com/PiMHll3.png)
116+
117+
### Creating New Gists or Collections
118+
119+
Once editing the document you can use the **Markdown Toolbar** to quickly access Markdown specific formatting features
120+
like the **Insert Link** icon:
121+
122+
![](http://i.imgur.com/XWCmjXl.png)
123+
124+
Which opens the Insert Link dialog and quickly create and link to new Gist or Collection by
125+
selecting the existing Gist or Collection you wish to use as a template:
126+
127+
![](http://i.imgur.com/IRBGD4V.png)
128+
129+
This lets you quickly create multiple C# Gists using a copy of an existing Gists `packages.config` and
130+
supporting `.cs` source files, significantly reducing the effort for creating multiple C# samples.
131+
132+
### Uploading Images
133+
134+
You can add images to your document by click on the Insert Image icon below:
135+
136+
![](http://i.imgur.com/oRe5UVV.png)
137+
138+
This will open the **Insert Image** dialog where you can drag multiple images to upload them
139+
to imgur and embed them in your document:
140+
141+
![](http://i.imgur.com/n8zYoqJ.png)
142+
143+
After each image has finished uploading to Imgur, it will be embedded in your document from your
144+
Cursors position using the Markdown Image Format below:
145+
146+
```
147+
![](http://i.imgur.com/n8zYoqJ.png)
148+
```
149+
150+
### Navigating, Browsing and Editing Collections
151+
152+
As you're authoring your Markdown Document you can freely jump between different Gists or Collections
153+
as Gistlyn automatically saves as-you-type so you can use the **Back** button to jump back
154+
to your new collection as you left it without missing a beat.
155+
156+
After navigating away from your page, the arrow icons below will appear to indicate what you're
157+
editing on the left no longer matches the same page on the right:
158+
159+
![](http://i.imgur.com/JATmJJ8.png)
160+
161+
Use the top **right arrow** icon to load the page you're editing in the preview window on the right
162+
to load the real-time preview of your Markdown document.
163+
164+
Use the bottom **left arrow** icon to load the Collection you're viewing on the right in the Editor.
165+
166+
## The Truly Empty ASP.NET Template
167+
168+
![](http://i.imgur.com/ZCHoJFA.png)
169+
170+
Over the years it's becoming harder and harder to create an Empty ASP.NET VS.NET Template as it
171+
continues to accumulate more cruft, unused dlls, hidden behavior, hooks into external services and
172+
other unnecessary bloat. Most of the bloat added since ASP.NET 2.0 for the most part has been unnecessary
173+
yet most .NET developers end up living with it because it's in the default template and they're
174+
unsure what each unknown dlls and default configuration does or what unintended behavior it will
175+
cause down the line if they remove it.
176+
177+
For ServiceStack and other lightweight Web Frameworks this added weight is completely unnecessary
178+
and can be safely removed.
179+
E.g. [most ServiceStack Apps just needs a few ServiceStack .dlls](https://github.com/ServiceStackApps/Chat#super-lean-front-and-back)
180+
and a [single Web.config mapping](https://github.com/ServiceStack/ServiceStack/wiki/Create-your-first-webservice#register-servicestack-handler)
181+
to tell ASP.NET to route all calls to ServiceStack. Any other ASP.NET config you would add in
182+
ServiceStack projects is just to get ASP.NET to disable any conflicting default behavior, e.g:
183+
184+
```xml
185+
<appSettings>
186+
<add key="webPages:Enabled" value="false" />
187+
</appSettings>
188+
```
189+
190+
Tells ASP.NET to stop hijacking Razor Views, required even when no ASP.NET Web Pages or MVC
191+
dlls are referenced. If using
192+
[Server Events](https://github.com/ServiceStack/ServiceStack/wiki/Server-Events)
193+
you'll also need to disable dynamic compression:
194+
195+
```xml
196+
<system.webServer>
197+
<urlCompression doStaticCompression="true" doDynamicCompression="false" />
198+
</system.webServer>
199+
```
200+
201+
To prevent ASP.NET from buffering responses, required even when `HttpResponseBase.BufferOutput=false`.
202+
203+
Or to reduce unnecessary requests and speed up iteration times, you can disable Browser Link with:
204+
205+
```xml
206+
<appSettings>
207+
<add key="vs:EnableBrowserLink" value="false"/>
208+
</appSettings>
209+
```
210+
211+
### The Minimal ASP.NET Template we wanted
212+
213+
We've decided to reverse this trend and instead of focusing on what can be added, we're
214+
focusing on what can be removed whilst still remaining useful for most modern ASP.NET Web Apps.
215+
216+
With this goal we've reduced the ASP.NET Empty Template down to a single project with
217+
the only external dependency being Roslyn:
218+
219+
![](http://i.imgur.com/jKFga3J.png)
220+
221+
Most dlls have been removed and the `Web.config` just contains registration for Roslyn and config for disabling
222+
ASP.NET's unwanted default behavior:
223+
224+
```xml
225+
<configuration>
226+
<appSettings>
227+
<add key="vs:EnableBrowserLink" value="false"/>
228+
<add key="webPages:Enabled" value="false" />
229+
</appSettings>
230+
231+
<system.web>
232+
<httpRuntime targetFramework="4.5"/>
233+
<compilation debug="true"/>
234+
</system.web>
235+
236+
<system.webServer>
237+
</system.webServer>
238+
239+
<system.codedom>
240+
<compilers>
241+
<compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.CSharpCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:6 /nowarn:1659;1699;1701"/>
242+
<compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.VBCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:14 /nowarn:41008 /define:_MYTYPE=\&quot;Web\&quot; /optionInfer+"/>
243+
</compilers>
244+
</system.codedom>
245+
</configuration>
246+
```
247+
248+
The only `.cs` file is an Empty `Global.asax.cs` with an empty placeholder for running custom code on Startup:
249+
250+
```csharp
251+
using System;
252+
253+
namespace WebApplication
254+
{
255+
public class Global : System.Web.HttpApplication
256+
{
257+
protected void Application_Start(object sender, EventArgs e)
258+
{
259+
260+
}
261+
}
262+
}
263+
```
264+
265+
And that's it! `ASP.NET Empty` is a single project empty ASP.NET Web Application with no additional references
266+
which we wont be adding to in future other than any configuration necessary to disable default ASP.NET behavior
267+
or enable C#'s latest language features so you can safely use this template for creating small stand-alone
268+
ASP.NET Web Apps using lightweight Web Frameworks like ServiceStack or [Nancy](http://nancyfx.org/).
269+
270+
### Minimal but still Useful
271+
272+
You can then easily [Convert this empty template into a functional ServiceStack Web App](https://github.com/ServiceStack/ServiceStack/wiki/Create-your-first-webservice) by:
273+
274+
1) Installing [ServiceStack and any other dependency](https://github.com/ServiceStackApps/Todos/blob/master/src/Todos/packages.config) you want to use, e.g:
275+
276+
PM> Install-Package ServiceStack
277+
PM> Install-Package ServiceStack.Redis
278+
279+
2) Adding the [ASP.NET HTTP Handler mapping](https://github.com/ServiceStackApps/Todos/blob/fdcffd37d4ad49daa82b01b5876a9f308442db8c/src/Todos/Web.config#L34-L39) to route all requests to ServiceStack:
280+
281+
```xml
282+
<system.webServer>
283+
<validation validateIntegratedModeConfiguration="false"/>
284+
<handlers>
285+
<add path="*" name="ServiceStack.Factory" type="ServiceStack.HttpHandlerFactory, ServiceStack" verb="*" preCondition="integratedMode" resourceType="Unspecified" allowPathInfo="true"/>
286+
</handlers>
287+
</system.webServer>
288+
```
289+
290+
3) Adding your [ServiceStack AppHost and Services in Global.asax.cs](https://github.com/ServiceStackApps/Todos/blob/master/src/Todos/Global.asax.cs).
291+
292+
That's all that's needed to create a functional Web App, which in this case creates a
293+
[Backbone TODO compatible REST API with a Redis back-end](https://github.com/ServiceStackApps/Todos/)
294+
which can power all [todomvc.com](http://todomvc.com) Single Page Apps.
295+
296+
## Generating API Keys for Existing Users
297+
298+
Whilst not a feature in ServiceStack, this script is useful if you want to enable ServiceStack's
299+
[API Key AuthProvider](https://github.com/ServiceStack/ServiceStack/wiki/API-Key-AuthProvider)
300+
but you have existing users you also want to generate API Keys for.
301+
302+
You can add the script below (which only needs to be run once) to your `AppHost.Configure()` which will
303+
use the configuration in your registered `ApiKeyAuthProvider` to generate new keys for all existing users
304+
that don't have keys.
305+
306+
This example assumes the typical scenario of using an `OrmLiteAuthRepository` to store your Users in an RDBMS:
307+
308+
```csharp
309+
AfterInitCallbacks.Add(host =>
310+
{
311+
var authProvider = (ApiKeyAuthProvider)
312+
AuthenticateService.GetAuthProvider(ApiKeyAuthProvider.Name);
313+
using (var db = host.TryResolve<IDbConnectionFactory>().Open())
314+
{
315+
var userWithKeysIds = db.Column<string>(db.From<ApiKey>()
316+
.SelectDistinct(x => x.UserAuthId)).Map(int.Parse);
317+
318+
var userIdsMissingKeys = db.Column<string>(db.From<UserAuth>()
319+
.Where(x => userWithKeysIds.Count == 0 || !userWithKeysIds.Contains(x.Id))
320+
.Select(x => x.Id));
321+
322+
var authRepo = (IManageApiKeys)host.TryResolve<IAuthRepository>();
323+
foreach (var userId in userIdsMissingKeys)
324+
{
325+
var apiKeys = authProvider.GenerateNewApiKeys(userId.ToString());
326+
authRepo.StoreAll(apiKeys);
327+
}
328+
}
329+
});
330+
```
331+
332+
If using another Auth Repository backend you will need to modify this script to fetch the userIds for
333+
all users missing API Keys for the data persistence back-end you're using.
334+
335+
## Other Features
336+
337+
### Auto rewriting of HTTPS Links
338+
339+
ServiceStack now automatically rewrites outgoing links to use `https://` for Requests that were forwarded
340+
by an SSL-terminating Proxy and containing the `X-Forwarded-Proto = https` HTTP Header.
341+
You can override `AppHost.UseHttps()` to change this behavior.
342+
343+
344+
# [v4.0.62 Release Notes](https://github.com/ServiceStack/ServiceStack/blob/master/docs/2016/v4.0.62.md)

0 commit comments

Comments
 (0)