Silverlight SDK

Have you ever rated a topic on MSDN or provided a comment and a rating?

Have you ever wondered if anyone looks at your rating or comment? The answer is yes.

We (the User Education team) roll up the ratings data, and in particular, look at topics that get a lot of hits, but low ratings. We use any comments we get about a high hit-rate/low-rated topic to guide improvements to the topic. Honestly, it's difficult know what sort of improvements to make when the only comments we receive are expletives or rants about the product. I know I am asking a lot, but if you rate a topic, please provide a quick comment about what you like or don't like about it. If you had a certain expectation when you went to that topic, and we didn't meet it, let us know why. We'll use your feedback to drive improvements. We really will!

--Cheryl

Because of the nature of Silverlight 2's API library, and its relationship with the APIs in the .NET Framework, finding content in the MSDN library using Search can be frustrating. (Even more frustrating than usual, that is :-P )

 Following are some tips and tricks that can help you find the Silverlight-specific information you are looking for, and avoid search hits that take you to topics that really mainly apply to .NET Framework (and perhaps even older versions of the Framework).

Note that these tips and tricks were tested using the main MSDN Search functionality powered by search.microsoft.com, but some of the basic concepts should also help with results using other search engines.

The brute force trick, API version: When you search for an API you know the name of, always use a string in the form of apiName apiType Silverlight. For instance, instead of just searching for "StackPanel", search for "StackPanel Class Silverlight". Note that adding the apiType will help push the managed API on top of the unmanaged (Silverlight 1.0) API in the results. If that's NOT what you want (you wanted the 1.0 one) typically omitting apiType will push the unmanaged one higher.

The brute force trick, conceptual version: Use a string in the form of wordOrPhraseICareAbout Silverlight, for instance "Layout Silverlight". Sometimes, you can maybe get really targeted results if you also include the word "Overview" or "How-To"; this will help push down blog results. But read on below for an even better way.

The filter trick: Guess what? MSDN has technology filtering on search results. For some development scenarios these filters are a mixed bag but for Silverlight they work pretty well! You need to be on an actual Live Search page to use this; there's no technology filter on the Quick Search (and also this is a feature specific to Live Search, not present on other search pages). To get there fast, just use one of the brute force tips suggested above. Once on the Live Search page, look in detail at the Live Search box at the top of the page (as in, don't just skip it like you usually do ;-) ). You'll see Refine by Topic and Refine by Source options. If you set these to Silverlight and Library Documentation and Articles, you can really up the prominence of the entry-level topics that the SDK writing team wanted you to see first.

The geeky versioning trick: OK suppose you ignored all my other advice and searched for some API like MeasureOverride, and ended up on the reference page for the .NET / WPF version of the API. You might have noticed that there's a little box on the upper right that you can use to bounce around between .NET framework versions, in this case from 3.5 to 3.0, useful if you happen to be targeting a 3.0 runtime and are a .NET developer. But sadly, no quick way to get to the "Silverlight version". All is not lost! You can get there from here. All you need to do is a little address bar URL hackery. So, up in the address bar, change that URI http://msdn.microsoft.com/en-us/library/system.windows.frameworkelement.measureoverride.aspx to insert the string "(vs.95)" right before the ".aspx". So for this example http://msdn.microsoft.com/en-us/library/system.windows.frameworkelement.measureoverride(vs.95).aspx. Viola! Now you are at the Silverlight "version", which happens to be an advancement of the .NET framework version ID's for geeky reasons that I totally don't want to get into. (And, in case you care, the little box can take you "back" to full .NET 3.5 or 3.0 versions now.)

The versioning trick doesn't generally work with conceptual topics, although there are a few topics that cover general CLR that really are re-versioned .NET -> Silverlight under the same scheme. But don't rely on that.

(BTW, sometimes, you can use some of the information on .NET 3.5 page like MeasureOverride, but you'd have to be really an expert on WPF and Silverlight to know the pitfalls. And if that's true of you ... why did you need this documentation page again? ;-) )

- wolf

Just a quick note that one of the breaking changes from beta 2 was that the WatermarkedTextBox control was removed. To find out why and how to work around this breaking change, check out Kathy Kam's blog WatermarkedTextBox for Silverlight 2 Beta 2.

 - Sam

You want to get a CHM file of all the Silverlight 2 Beta 2 MSDN docs? Get it here. Using this file you don't have to deal with the delay of online browsing and when you do a search, you are only searching in Silverlight content. 

Note that these docs are the exact same as the Silverlight docs on MSDN online. Of course this offline CHM will become outdated over time which means you'll have to watch for the next offline CHM to be available.

 - Sam

Check out the Silverlight page on Microsoft.com for install links and Silverlight.net for quickstarts, videos, tutorials, forums and links to the documentation. If you want to go straight to the documentation, find it here: Silverlight Documentation.

--Cheryl

The DataGrid Beta 2 breaking change list came in a bit too late to make the official documentation. We'll add that for the next doc refresh, but until then, you can see the DataGrid-only breaking changes list here, or the complete, updated list of all breaking changes between Beta 1 and Beta 2 in Word 2007 format here.

For DataGrid, most of the changes are API name changes that will require updates to your Beta 1 code. You can fix these by waiting for compiler errors, and then doing a search in the breaking changes list for the broken API names.

Additionally, however, there are a few behavior changes, which are harder to catch because they don't show up as compiler errors. These changes currently affect the doc snippet. We'll get that updated for the next doc refresh as well, but until then, the next few sections will describe what you have to do to avoid some problems and take advantage of the cool new autosizing feature.

Autogenerated Columns

One Beta 2 gotcha is with autogenerated columns. This is a behavior change that manifests as unexpected columns or a blank screen and a run time exception.

Here's the relevant bit of the breaking changes list:

AutoGenerateColumns behavior modified

...

Beta 2

• dataGrid.AutoGenerateColumns is true by default
• ...
• Column generation is delayed until the DataGrid has loaded ...

Because AutoGenerateColumns is now true by default, you must set it to false when you configure columns explicitly, otherwise you'll get both configured and generated columns. This affects the last two demo DataGrid controls in the doc snippet (which you can only see by fixing the next issue first).

The delay in column generation affects the first three DataGrid controls in the snippet. Here is an example of the broken code:

            // DOESN'T WORK

            dataGrid1.ItemsSource = Customer.GetSampleCustomerList();

            dataGrid1.Columns.RemoveAt(2);           

When the RemoveAt method is called, the columns have not yet been autogenerated, so this code throws an ArgumentOutOfRangeException. Here's a quick fix, using a lambda expression to handle the AutoGeneratingColumn event:

            dataGrid1.ItemsSource = Customer.GetSampleCustomerList();

            dataGrid1.AutoGeneratingColumn += (s, e) =>

                { if (e.Column.Header.Equals("Address")) e.Cancel = true; };

Automatic Sizing

Another behavior change that you won't encounter in a compiler error is with automatic sizing. Luckily, this change doesn't break anything. If you have hard-coded column widths in XAML, those values will continue to work. However, you might want to replace them with automatic sizing values in case your cell or header contents change.

Many size-related properties, such as the column Width property, now take a DataGridLength structure instead of a double. A DataGridLength structure represents either a double or one of the following automatic-sizing values (which you can specify in XAML):  "SizeToCells", "SizeToHeader", or "Auto". (The "Auto" value means "size to both cells and headers".)

See Also

DataGrid Beta 2 Breaking Changes 

Breaking Changes for Silverlight 2 Beta 2 (corrections and additions)

Breaking Changes Between Beta 1 and Beta 2 on MSDN

With Silverlight 2 Beta 2 coming out there were a number of changes that will break applications written for older builds of Silverlight. We published a document that listed these changes and how to fix them (Breaking Changes Between Beta 1 and Beta 2) but this document is now a bit out of date due to corrections/additions made after the document was locked down.

Attached is a more complete up-to-date version of this document. To get this attachment, scroll down to the bottom of this post. Note that I've attached a Word 2007 version and a Word 97-2003 version. In addition, below is a list of changes/additions that might differ between this updated document and those that shiped with the SDK. You can use the attached new version of the document to see the correct changes.

1. Controls no longer allow events to bubble up (in other words, controls eat events). Jesse Liberty's blog Who Ate my MouseDown Event? for more information. Also, the section in the breaking changes doc titled RoutedEventArgs.Handled=true Events No Longer Bubble but it is perhaps not very discoverable under that title.

2. A whole bunch DataGrid breaking changes. The changes are to numerous to list in this post. Download the attached Word file to get them. The online version of the breaking changes doc doesn't have this while the loose Word file that ships with the offline SDK does so you may or may not already have this info depending on your source...

3. Wrong URL in the sample crossdomain.xml file. It should look like this:

crossdomain.xml

<?xml version="1.0"?>

<!DOCTYPE cross-domain-policy SYSTEM

  "http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>

  <allow-http-request-headers-from domain="* " headers="*" />

</cross-domain-policy>

4. Calendar/DatePicker Changes section is wrong. It should look like this:

Who Is Affected: Those using DatePicker or Calendar.

Summary

The following changes were made to the Calendar and DatePicker.

Calendar

·         [Remove] Style DayStyle

·         [Remove] Style MonthStyle

·         [Removed] EventHandler<CalendarDateChangedEventArgs> DateSelected

·         [Added] EventHandler<SelectionChangedEventArgs> SelectedDatesChanged

DatePicker

·         [Remove] ToolTip ToolTip

·         [Remove] EventHandler<DatePickerTextParseErrorEventArgs> TextParseError

·         [Added] EventHandler<DatePickerDateValidationErrorEventArgs> DateValidationError

·         [Removed] EventHandler<DatePickDateChangedEventArgs> DateSelected

·         [Added] EventHandler<SelectionChangedEventArgs> SelectedDateChanged

Calendar and DatePicker

·         [Remove] bool IsEnabled {get; set;}

·         [Remove] DateTime? SelectableDateStart

·         [Remove] DateTime? SelectableDateEnd

·         [Remove] bool AreDatesInPastSelectable

5.  System.ServiceModel.ClientBase Changes section is wrong. It should look like this:

Who Is Affected: Those using System.ServiceModel.ClientBase.Open() and Close() or System.ServiceModel.ClientBase.Dispose().

Summary

System.ServiceModel.ClientBase.Open() and Close() and System.ServiceModel.ClientBase.Dispose() were removed.

Fix Required

Workarounds for code using Open():

·         [preferred] Don’t call it: on the first web service call we will automatically do Open asynchronously, so you don’t need to call it explicitly.

·         [preferred] Change code to use OpenAsync and the OpenCompleted event

·         [less preferred] Cast the proxy to ICommunicationObject and use BeginOpen/EndOpen

·         [not recommended] Cast the proxy to ICommunicationObject and use Open()

Workarounds for code using Close():

·         [preferred] change code to use CloseAsync.  The CloseCompleted event is not usually necessary as you don’t usually need notification when Close completes

·         [less preferred] don’t call Close at all.  Resources used by the proxy will eventually be reclaimed

·         [less preferred] Cast the proxy to ICommunicationObject and use BeginClose/EndClose

·         [not recommended] Cast the proxy to ICommunicationObject and use Close()

Workarounds for code using Dispose() or the ‘using’ C# pattern:

·         [preferred] change code to call CloseAsync

·         [less preferred] see other alternatives for Close() above

6. The following was added to the Miscellaneous API changes section:

·         XmlAnyElementAttributes class no longer implements Collection<T>, ICollection<T>, IEnumerable<T>, or IList<T>

·         XmlArrayItemAttributes class no longer implements Collection<T>, ICollection<T>, IEnumerable<T>, or IList<T>

·         XmlElementAttributes class no longer implements Collection<T>, ICollection<T>, IEnumerable<T>, or IList<T>

·         System.Runtime.Serialization.ExtensionDataObject class was removed.

·         XmlAnyAttributeAttribute class was removed.

·         XmlAttributes.XmlAnyAttribute member was removed.

·         CodeIdentifier class was removed.

·         CodeIdentifiers class was removed.

·         Removed: delegate types XmlSerializationCollectionFixupCallback, XmlSerializationFixupCallback, and XmlSerializationReadCallback

·         The following protected members of XmlSerializationReader were removed:

o    [remove] protected void AddFixup(Fixup fixup);

o    [remove] protected void AddFixup(CollectionFixup fixup);

o    [remove] protected void AddReadCallback(String name, String ns, Type type, XmlSerializationReadCallback read);

o    [remove] protected void AddTarget(String id, Object o);

o    [remove] protected void FixupArrayRefs(Object fixup);

o    [remove] protected Int32 GetArrayLength(String name, String ns);

o    [remove] protected Object GetTarget(String id);

o    [remove] protected Boolean ReadReference(out String fixupReference);

o    [remove] protected Object ReadReferencedElement(String name, String ns);

o    [remove] protected Object ReadReferencedElement();

o    [remove] protected void ReadReferencedElements();

o    [remove] protected Object ReadReferencingElement(String name, String ns, Boolean elementCanBeType, out String fixupReference);

o    [remove] protected Object ReadReferencingElement(String name, String ns, out String fixupReference);

o    [remove] protected Object ReadReferencingElement(out String fixupReference);

o    [remove] protected void Referenced(Object o);

o    [remove] protected void UnreferencedObject(String id, Object o);

o    [remove] protected class CollectionFixup; // removed

o    [remove] protected internal class Fixup; // removed

·         The following protected members of XmlSerializationWriter were removed:

o    [remove] protected void AddWriteCallback(Type type, String typeName, String typeNs, XmlSerializationWriteCallback callback);

o    [remove] protected void WriteId(Object o);

o    [remove] protected void WritePotentiallyReferencingElement(String n, String ns, Object o, Type ambientType, Boolean suppressReference);

o    [remove] protected void WritePotentiallyReferencingElement(String n, String ns, Object o, Type ambientType);

o    [remove] protected void WritePotentiallyReferencingElement(String n, String ns, Object o, Type ambientType, Boolean suppressReference, Boolean isNullable);

o    [remove] protected void WritePotentiallyReferencingElement(String n, String ns, Object o);

o    [remove] protected void WriteReferencedElements();

o    [remove] protected void WriteReferencingElement(String n, String ns, Object o);

o    [remove] protected void WriteReferencingElement(String n, String ns, Object o, Boolean isNullable);

o    [remove] protected void WriteRpcResult(String name, String ns);

7. The Scrollviewer template elements changed.

To fix: Go to the ScrollViewer template documentation or re-generate a new default template in Blend 2.5. This will get you the correct names of the template elements.

8. Can't get UI elements by name if hosted in ContentControl (ScrollViewers etc).

9. You can find a workaround for the removal of the WatermarkedTextBox control here: WatermarkedTextBox for Silverlight 2 Beta 2.

Silverlight 2 Beta 2 includes a number of incremental improvements based on customer feedback.   Changes include improvements to controls, templating, Deep Zoom, performance, further compatibility with WPF, and much more.  For a full list of changes, see below:

Note: If you want to see a list of breaking changes between Beta 1 and Beta 2 go here.

·          Animation
1.       Support for animating custom data points
2.       Object Animation support (animating structs)

·          DeepZoom
1.        New file format completely XML based. Also, there will be a new Deep Zoom Composer tool that will allow you to create these new file types.
2.        MultiScaleTileSource  (implement a tile source to existing tile databases)
3.        Better notifications when sub-images enter the view

·          Controls
1.       New TabControl
2.       DataGrid improvements: Autosize, Reorder, Sort, Performance increase, and more
3.       Calendar now supports multi-selection and blackout dates
4.       Improved Templating Model: Visual State Manager
5.       Control properties changes (Background, Tooltip, FontFamily, FontSize…)
6.       Including controls in the runtime instead of having them packaged in app package

·          TextBox
1.       IME Level 3 input support on Windows and Level 1 on Mac
2.       Text wrapping and multiline selection highlighting in textbox
3.       Scrollbar Support
4.       Document Level Navigation keys

·          Improvements in error handling, reporting

·          Property System/Parser
1.       DependencyProperty.Register/RegisterAttached now supports PropertyMetadata
2.       DependencyObject.ClearValue
3.       Visual Tree Helper

·          Data Binding
1.       Per-binding level validation
2.       Support for element syntax for binding markup extension
3.       Binding to Attached Properties
4.       ItemsControl Extensibility (OnItemsChanged method)
5.       Fallback in Value Conversion (Binding.UnsetValue)

·          Input
1.       Limited keyboard support in FullScreen mode (arrow, tab, enter, home, end, pageup/pagedown, space)
2.       Managed APIs for Inking

·          Networking and Data
1.       Cross Domain support in Sockets
2.       Cross Domain security enhancements
3.       BrowserHttpWebRequest and WebClient callable from BackGround Threads
4.       Upload support for WebClient
5.       UI for isolated storage (ability to change quota)
6.       Duplex communications (“push” from Server to Silverlight client)
7.       LINQ-to-JSON
8.       Configuration support for web service proxies
9.       Significantly improved SOAP interop
10.   “Add New Item” template in Visual Studio for “Silverlight-enabled WCF Service”
11.   ADO.NET Data Services support

·          UIAutomation and Accessibility support in platform

·          Media
1.       Platform support for Adaptive streaming
2.       Silverlight DRM, Powered by PlayReady
3.       Basic SSPL support

·          Localization
1.        Changes in application model for multilingual apps (one xap per supported locale)
2.        Expanded localization languages of runtime and SDK
3.        Japanese SDK Installer and documentation (July 17)

·          Several changes for WPF compatibility

·          Remote Debugging for VB on Mac

·          CLR
1.        Developer Runtime Package facilitate development (localized strings, debugging binaries, etc)
2.        Support the OS fallback logic for resources
3.        CurrentCulture and CurrentUICulture Isolation

·          DLR
1.        Performance improvements
2.        Various new DLR and IronPython 2.0 Beta 2 language features
3.        Various new IronRuby Features

David Pugmire
Product Manager - Silverlight

Well, the news is out. Silverlight 2 Beta 2 will release sometime later this week. There are many new features and changes from Beta 1. Since I document many of the controls and oversee the control overview material, I'll tell you about some of the product changes related to controls:

-TabControl added to the SDK

-Many controls moved from the SDK to the runtime. Also many of the controls were brought in line with their WPF counterparts.  For example, controls have changed assemblies and namespaces and some of the control APIs have been tweaked. This makes things easier for developers that are targeting both Silverlight and WPF for their applications.

-Templating for controls was simplified with the introduction of Visual State Manager

On the doc side of things we are taking a minimalist approach for the control overview material. I've eliminated many of the mostly empty portal/navigation topics, and instead listed the controls in a topic named Control Gallery. In addition to a written description for the controls, for many I've included an images and a link to a running sample. I've also written a topic that lists controls by function and created a topic named Getting Started with Controls that shows you how to complete tasks common to all controls.

Unfortunately the content isn't live yet, but I'll link to the top-level topic that will take you to some of the topics I've mentioned. I would love some feedback on what you think about the control material; what you like, don't like and why. The following link is good now, but points to the old material. The content will be updated with Beta2 releases, which I mentioned before should be by the end of the week. Check it out here: Silverlight Control Conceptual Material

Also, I am sure many of my peers on the Silverlight User Education team will be posting soon about changes in their feature areas.

Stay Tuned!

--Cheryl

As I was digging around in an old spec, I came across some very enlightening drawings which I pushed through art review and I will now share with you.  Ashish wrote a nice post on the layout and rendering engines which might help you understand what's happening when you put something in a panel.  This is particularly useful if you are trying to do a complex layout.  Also, as a side note, I really recommend putting background colors on your element or using borders when you are first trying to get something to layout properly.  It can really help you figure out what is going on. 

As I was going through my list of APIs to document, I stumbled onto the LayoutInformation class.  In it are three methods, two of which I found especially interesting (GetLayoutSlot and GetLayoutClip).  The other one (GetLayoutExceptionElement) I'm sure would be interesting if you were getting an exception during layout.  But happily I have not run across that issue.

As I discussed in my previous post Creating a Custom Panel, a lot of the layout process is really about positioning the bounding box (or layout slot) that surrounds each element.  If you have trouble visualizing this, you are going to love these pictures.  GetLayoutSlot returns the rectangle that is your bounding box.  The element that is inside the layout slot can be bigger or smaller.  If its smaller, then it is positioned inside the layout slot based on it's alignment properties like so:

If the element is bigger than its layout slot, then it will be clipped and only the area which is inside of the layout slot will be displayed. 

This visible region (outlined in red) is what GetLayoutClip returns to you.  The size of the layout slot can change as elements are added or removed from the parent container.  Basically every time the layout engine is called, there is a chance for the layout slot to change.

 Here's some code that calls GetLayoutSlot and draws the returned rectangle.  First the XAML:

<Grid x:Name="LayoutRoot" Background="White">

    <Grid.RowDefinitions>

        <RowDefinition/>

        <RowDefinition/>

    </Grid.RowDefinitions>

    <StackPanel x:Name="sp1" Grid.Row="0" Background="AliceBlue" Height="100" Width="200"

                HorizontalAlignment="Left" VerticalAlignment="Top" >

         <Rectangle x:Name="rect1" Fill="Blue"  Width="100" Height="50" ></Rectangle>

    </StackPanel>

    <Button Content="Get Layout Slot" Grid.Row="1" Width="150" Height="50"

            Click="Button_Click" HorizontalAlignment="Left"/>

</Grid>

And here's the click event handler: