Skip to content

Commit 103ecff

Browse files
mythzmythz
committed
Add v4.0.24 release notes
1 parent 7c970fc commit 103ecff

File tree

1 file changed

+304
-1
lines changed

1 file changed

+304
-1
lines changed

‎release-notes.md‎

Lines changed: 304 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,309 @@
11
# Release Notes
22

3-
## v4.0.23 Release Notes
3+
# v4.0.24 Release Notes
4+
5+
## [Server Events](https://github.com/ServiceStackApps/Chat)
6+
7+
In keeping with our quest to provide a simple, lean and deep integrated technology stack for all your web framework needs we've added support in this release for Server push communications with our initial support for [Server Sent Events](http://www.html5rocks.com/en/tutorials/eventsource/basics/).
8+
9+
[Server Sent Events](http://www.html5rocks.com/en/tutorials/eventsource/basics/) (SSE) is an elegant [web technology](http://dev.w3.org/html5/eventsource/) for efficiently receiving push notifications from any HTTP Server. It can be thought of as a mix between long polling and one-way WebSockets and contains many benefits over each:
10+
11+
- **Simple** - Server Sent Events is just a single long-lived HTTP Request that any HTTP Server and Web Framework can support
12+
- **Efficient** - Each client uses a single TCP connection and each message avoids the overhead of HTTP Connections and Headers that's [often faster than Web Sockets](http://matthiasnehlsen.com/blog/2013/05/01/server-sent-events-vs-websockets/).
13+
- **Resilient** - Browsers automatically detect when a connection is broken and automatically reconnects
14+
- **Interoperable** - As it's just plain-old HTTP, it's introspectable with your favorite HTTP Tools and even works through HTTP proxies (with buffering and checked-encoding off).
15+
- **Well Supported** - As a Web Standard it's supported in all major browsers except for IE which [can be enabled with polyfills](http://html5doctor.com/server-sent-events/#yaffle).
16+
17+
Server Events provides a number of API's that allow sending messages to:
18+
19+
- All Users
20+
- All Users subscribed to a channel
21+
- A Single Users Subscription
22+
23+
It also includes deep integration with ServiceStack's [Sessions](https://github.com/ServiceStack/ServiceStack/wiki/Sessions) and [Authentication Providers](https://github.com/ServiceStack/ServiceStack/wiki/Authentication-and-authorization) which also sending messages to uses using either:
24+
25+
- UserAuthId
26+
- UserName
27+
- Permanent Session Id (ss-pid)
28+
29+
### Registering
30+
31+
List most other [modular functionality](https://github.com/ServiceStack/ServiceStack/wiki/Plugins) in ServiceStack, Server Sent Events is encapsulated in a single Plugin that can be registered in your AppHost with:
32+
33+
```csharp
34+
Plugins.Add(new ServerEventsFeature());
35+
```
36+
37+
### [ServiceStack Chat (beta)](https://github.com/ServiceStackApps/Chat)
38+
39+
![Chat Overview](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Chat/chat-overview.gif)
40+
41+
To demonstrate how to make use Server Events we've created a cursory Chat web app for showcasing server push notifications packed with a number of features including:
42+
43+
- Anonymous or Authenticated access with Twitter, Facebook or GitHub OAuth
44+
- Joining any arbitrary user-defined channel
45+
- Private messaging
46+
- Command history
47+
- Autocomplete of user names
48+
- Highlighting of mentions
49+
- Grouping messages by user
50+
- Active list of users, kept live with:
51+
- Periodic Heartbeats
52+
- Automatic unregistration on page unload
53+
- Remote Control
54+
- Send a global announcement to all users
55+
- Toggle on/off channel controls
56+
- Change the CSS style of any element
57+
- Change the HTML document's title
58+
- Redirect users to any url
59+
- Play a youtube video
60+
- Display an image url
61+
- Raise DOM events
62+
63+
<img src="https://github.com/ServiceStack/Assets/blob/master/img/apps/Chat/vs-sln.png" alight="right" hspace="10">
64+
65+
Chat is another ServiceStack Single Page App Special showing how you can get a lot done with minimal effort and dependencies which delivers all these features in a tiny footprint built with vanilla jQuery and weighing just:
66+
67+
- [1 default.cshtml page](https://github.com/ServiceStackApps/Chat/blob/master/src/Chat/default.cshtml), with less than **170 lines of JavaScript** and **70 lines of HTML** markup
68+
- [2 ServiceStack Services](https://github.com/ServiceStackApps/Chat/blob/master/src/Chat/Global.asax.cs), entire backend in 1 `.cs` file
69+
- 1 ASP.NET Web Application project requiring only a sane **9 .NET dll** references
70+
71+
### Remote control
72+
73+
Chat features the ability to remotely control other users chat window with the client bindings in `/js/ss-utils.js`, providing a number of different ways to interact and modify a live webapp by either:
74+
75+
- Invoking Global Event Handlers
76+
- Modifying CSS via jQuery
77+
- Sending messages to Receivers
78+
- Raising jQuery Events
79+
80+
All options above are designed to integrate with an apps existing functionality by providing the ability to invoke predefined handlers and exported object instances as well as modify jQuery CSS and raising DOM events.
81+
82+
The [complete documentation](https://github.com/ServiceStackApps/Chat) in Chat is the recommended way to learn more about Server Events which goes through and explains how to use its Server and Client features.
83+
84+
## [ServiceStackVS](https://github.com/ServiceStack/ServiceStackVS) - ServiceStack's VS.NET Extension
85+
86+
Another exciting announcement is the initial release of [ServiceStackVS](https://github.com/ServiceStack/ServiceStackVS) - our VS.NET ServiceStack Extension containing the most popular starting templates for ServiceStack powered solutions:
87+
88+
![Visual Studio Templates](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackvs/vs-templates.png)
89+
90+
Each project template supports our [recommended multi-project structure](https://github.com/ServiceStack/ServiceStack/wiki/Physical-project-structure) promoting a clean architecture and Web Services best-practices, previously [documented in Email Contacts](https://github.com/ServiceStack/EmailContacts/#creating-emailcontacts-solution-from-scratch).
91+
92+
This is now the fastest way to get up and running with ServiceStack. With these new templates you can now create a new ServiceStack Razor, AngularJS and Bootstrap enabled WebApp, pre-wired end-to-end in seconds:
93+
94+
![AngularJS WalkThrough](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackvs/angularjs-overview.gif)
95+
96+
### Download ServiceStackVS
97+
98+
ServiceStackVS supports both VS.NET 2013 and 2012 and can be [downloaded from the Visual Studio Gallery](http://visualstudiogallery.msdn.microsoft.com/5bd40817-0986-444d-a77d-482e43a48da7)
99+
100+
[![VS.NET Gallery Download](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackvs/vsgallery-download.png)](http://visualstudiogallery.msdn.microsoft.com/5bd40817-0986-444d-a77d-482e43a48da7)
101+
102+
### VS.NET 2012 Prerequisites
103+
104+
- VS.NET 2012 Users must install the [Microsoft Visual Studio Shell Redistributable](http://www.microsoft.com/en-au/download/details.aspx?id=40764)
105+
- It's also highly recommended to [Update to the latest NuGet](http://docs.nuget.org/docs/start-here/installing-nuget).
106+
107+
> Alternatively if continuing to use an older version of the **NuGet Package Manager** you will need to click on **Enable NuGet Package Restore** after creating a new project to ensure its NuGet dependencies are installed.
108+
109+
### Feedback
110+
111+
We hope ServiceStackVS helps make ServiceStack developers more productive than ever and we'll look to continue improving it with new features. [Suggestions and feedback are welcome](http://servicestack.uservoice.com/forums/176786-feature-requests).
112+
113+
## [Authentication](https://github.com/ServiceStack/ServiceStack/wiki/Authentication-and-authorization)
114+
115+
### Saving User Profile Images
116+
117+
To make it easier to build Social Apps like Chat with ServiceStack we've started saving profile image urls (aka avatars) for the following popular OAuth providers:
118+
119+
- Twitter
120+
- Facebook
121+
- GitHub
122+
- Google OAuth2
123+
- LinkedIn OAuth2
124+
125+
The users profile url can be accessed in your services using the `IAuthSession.GetProfileUrl()` extension method which goes through the new `IAuthMetadataProvider` which by default looks in `UserAuthDetails.Items["profileUrl"]`.
126+
127+
### New IAuthMetadataProvider
128+
129+
A new [IAuthMetadataProvider](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/AuthMetadataProvider.cs) has been added that provides a way to customize the `authInfo` in all AuthProviders. It also allows overriding of how extended Auth metadata like `profileUrl` is returned.
130+
131+
```csharp
132+
public interface IAuthMetadataProvider
133+
{
134+
void AddMetadata(IAuthTokens tokens, Dictionary<string, string> authInfo);
135+
136+
string GetProfileUrl(IAuthSession authSession, string defaultUrl = null);
137+
}
138+
```
139+
140+
> To override with a custom implementation, register `IAuthMetadataProvider` in the IOC
141+
142+
### Saving OAuth Metadata
143+
144+
145+
The new `SaveExtendedUserInfo` property (enabled by default) on all OAuth providers let you control whether to save the extended OAuth metadata available (into `UserAuthDetails.Items`) when logging in via OAuth.
146+
147+
## [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite/)
148+
149+
### Loading of References in Multi-Select Queries
150+
151+
Previous support of pre-loading of references were limited to a single entity using `LoadSingleById` to automatically fetch all child references, e.g:
152+
153+
```csharp
154+
public class Customer
155+
{
156+
[AutoIncrement]
157+
public int Id { get; set; }
158+
public string Name { get; set; }
159+
160+
[Reference] // Save in CustomerAddress table
161+
public CustomerAddress PrimaryAddress { get; set; }
162+
163+
[Reference] // Save in Order table
164+
public List<Order> Orders { get; set; }
165+
}
166+
167+
var customer = db.LoadSingleById<Customer>(request.Id);
168+
customer.PrimaryAddress // Loads 1:1 CustomerAddress record
169+
customer.Orders // Loads 1:M Order records
170+
```
171+
172+
We've now also added support for pre-loading of references for multiple resultsets as well with `LoadSelect` which loads references for all results, e.g:
173+
174+
```csharp
175+
var customers = db.LoadSelect<Customer>(q => q.Name.StartsWith("A"));
176+
```
177+
178+
This is implemented efficiently behind the scenes where only 1 additional SQL Query is performed for each defined reference.
179+
180+
> As a design goal none of OrmLite Query API's perform N+1 queries.
181+
182+
### Self References
183+
184+
We've extended OrmLite [References support](https://github.com/ServiceStack/ServiceStack.OrmLite/#reference-support-poco-style) to support Self References for **1:1** relations where the foreign key property can be on the parent table, e.g:
185+
186+
```csharp
187+
public class Customer
188+
{
189+
...
190+
public int CustomerAddressId { get; set; }
191+
192+
[Reference]
193+
public CustomerAddress PrimaryAddress { get; set; }
194+
}
195+
```
196+
197+
Which maintains the same relationship as having the Foreign Key column on the child table instead, i,e:
198+
199+
```csharp
200+
public class CustomerAddress
201+
{
202+
public int CustomerId { get; set; }
203+
}
204+
```
205+
206+
### Support Foreign Key Attributes to specify Reference Fields
207+
208+
Previously definitions of references relied on [Reference Conventions](https://github.com/ServiceStack/ServiceStack.OrmLite/#reference-conventions) using either the C# Property Name or Property Aliases. You can now also use the [References and ForeignKey attributes](https://github.com/ServiceStack/ServiceStack.OrmLite/#new-foreign-key-attribute-for-referential-actions-on-updatedeletes) to specify Reference Properties, e.g:
209+
210+
```csharp
211+
public class Customer
212+
{
213+
[Reference(typeof(CustomerAddress))]
214+
public int PrimaryAddressId { get; set; }
215+
216+
[Reference]
217+
public CustomerAddress PrimaryAddress { get; set; }
218+
}
219+
```
220+
221+
> Reference Attributes take precedence over naming conventions
222+
223+
### Support for Stored Procedures with out params
224+
225+
A new `SqlProc` API was added returning an `IDbCommand` which can be used to customize the Stored Procedure call letting you add custom out parameters. The example below shows
226+
227+
```csharp
228+
string spSql = @"DROP PROCEDURE IF EXISTS spSearchLetters;
229+
CREATE PROCEDURE spSearchLetters (IN pLetter varchar(10), OUT pTotal int)
230+
BEGIN
231+
SELECT COUNT(*) FROM LetterFrequency WHERE Letter = pLetter INTO pTotal;
232+
SELECT * FROM LetterFrequency WHERE Letter = pLetter;
233+
END";
234+
235+
db.ExecuteSql(spSql);
236+
237+
var cmd = db.SqlProc("spSearchLetters", new { pLetter = "C" });
238+
var pTotal = cmd.AddParam("pTotal", direction: ParameterDirection.Output);
239+
240+
var results = cmd.ConvertToList<LetterFrequency>();
241+
var total = pTotal.Value;
242+
```
243+
244+
An alternative approach is to use the new overload added to the raw SQL API `SqlList` that lets you customize the Stored Procedure using a filter, e.g:
245+
246+
``csharp
247+
IDbDataParameter pTotal = null;
248+
var results = db.SqlList<LetterFrequency>("spSearchLetters", cmd => {
249+
cmd.CommandType = CommandType.StoredProcedure;
250+
cmd.AddParam("pLetter", "C");
251+
pTotal = cmd.AddParam("pTotal", direction: ParameterDirection.Output);
252+
});
253+
var total = pTotal.Value;
254+
```
255+
256+
### Minor OrmLite Features
257+
258+
- Use `OrmLiteConfig.DisableColumnGuessFallback=false` to disable fallback matching heuristics
259+
- Added [GenericTableExpressions](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/tests/ServiceStack.OrmLite.Tests/Expression/GenericTableExpressions.cs) example showing how to extend OrmLite to support different runtime table names on a single schema type.
260+
261+
## [AutoQuery](https://github.com/ServiceStack/ServiceStack/wiki/Auto-Query)
262+
263+
### Support for loading References
264+
265+
AutoQuery now takes advantage of OrmLite's new support for preloading child references which
266+
267+
```csharp
268+
public class Rockstar
269+
{
270+
public int Id { get; set; }
271+
public string FirstName { get; set; }
272+
public string LastName { get; set; }
273+
public int? Age { get; set; }
274+
275+
[Reference]
276+
public List<RockstarAlbum> Albums { get; set; }
277+
}
278+
```
279+
280+
### Improved OrderBy
281+
282+
Add support for inverting sort direction of individual orderBy fields using '-' prefix e.g:
283+
284+
```csharp
285+
// ?orderBy=Rating,-ImdbId
286+
var movies = client.Get(new SearchMovies { OrderBy = "Rating,-ImdbId" });
287+
288+
// ?orderByDesc=-Rating,ImdbId
289+
var movies = client.Get(new SearchMovies { OrderByDesc = "-Rating,ImdbId" });
290+
```
291+
292+
## ServiceStack.Text
293+
294+
- Add support for `OrderedDictionary` and other uncommon `IDictionary` types
295+
- WCF-style `JsConfig.OnSerializedFn` custom hook has been added
296+
- `JsConfig.ReuseStringBuffer` is enabled by default for faster JSON/JSV text serialization
297+
- Properties can also be ignored with `[JsonIgnore]` attribute
298+
299+
## Other Features
300+
301+
- New `[Exclude(Feature.Soap)]` attribute can be used to exclude types from XSD/WSDL's
302+
- XSD/WSDL's no longer including open generic types
303+
- Added `$.ss.getSelection()`, `$.ss.queryString()`, `$.ss.splitOnFirst()`, `$.ss.splitOnLast()` to /ss-utils.js
304+
- `TwitterAuthProvider` now makes authenticated v1.1 API requests to fetch user metadata
305+
306+
# v4.0.23 Release Notes
4307

5308
## [AutoQuery](https://github.com/ServiceStack/ServiceStack/wiki/Auto-Query)
6309

0 commit comments

Comments
 (0)