Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Walkthrough: Downloading Satellite Assemblies on Demand with the ClickOnce Deployment API Using the Designer

Windows Forms applications can be configured for multiple cultures through the use of satellite assemblies. A satellite assembly is an assembly that contains application resources for a culture other than the application's default culture.

As discussed in ClickOnce Deployment and Localization, you can include multiple satellite assemblies for multiple cultures within the same ClickOnce deployment. By default, ClickOnce will download all of the satellite assemblies in your deployment to the client machine, although a single client will probably require only one satellite assembly.

This walkthrough demonstrates how to mark your satellite assemblies as optional, and download only the assembly a client machine needs for its current culture settings.

NoteNote:

For testing purposes, the following code examples programmatically set the culture to ja-JP. See the "Next Steps" section later in this topic for information on how to adjust this code for a production environment.

This topic assumes that you know how to add localized resources to your application using Microsoft Visual Studio 2005. For detailed instructions, see Walkthrough: Localizing Windows Forms.

To mark satellite assemblies as optional

  1. Build your project. This will generate satellite assemblies for all of the cultures you are localizing to.

  2. Right-click on your project name in Solution Explorer, and click Properties.

  3. Click the Publish tab, and then click Application Files.

  4. Select the Show all files check box to display satellite assemblies. By default, all satellite assemblies will be included in your deployment and will be visible in this dialog box.

    A satellite assembly will have a name in the form isoCode\ApplicationName.resources.dll, where isoCode is a language identifier in RFC 1766 format.

  5. Click New... in the Download Group list for each language identifier. When prompted for a download group name, enter the language identifier. For example, for a Japanese satellite assembly, you would specify the download group name ja-JP.

  6. Close the Application Files dialog box.

To download satellite assemblies on demand in C#

  1. Open the Program.cs file. If you do not see this file in Solution Explorer, select your project, and on the Project menu, click Show All Files.

  2. Use the following code to download the appropriate satellite assembly and start your application.

    using System;
    using System.Collections.Generic;
    using System.Windows.Forms;
    using System.Threading;
    using System.Globalization;
    using System.Deployment.Application;
    using System.Reflection;
    
    namespace ClickOnce.SatelliteAssemblies
    {
        static class Program
        {
            [STAThread]
            static void Main()
            {
                Application.EnableVisualStyles();
                Application.SetCompatibleTextRenderingDefault(false);
                Thread.CurrentThread.CurrentUICulture = new CultureInfo("ja-JP");
    
                // Call this before initializing the main form, which will cause the resource manager 
                // to look for the appropriate satellite assembly.
                GetSatelliteAssemblies(Thread.CurrentThread.CurrentCulture.ToString());
    
                Application.Run(new Form1());
            }
    
            static void GetSatelliteAssemblies(string groupName)
            {
                if (ApplicationDeployment.IsNetworkDeployed)
                {
                    ApplicationDeployment deploy = ApplicationDeployment.CurrentDeployment;
    
                    if (deploy.IsFirstRun)
                    {
                        try
                        {
                            deploy.DownloadFileGroup(groupName);
                        }
                        catch (DeploymentException de)
                        {
                            // Log error. Do not report this error to the user, because a satellite 
                            // assembly may not exist if the user's culture and the application's 
                            // default culture match.
                        }
                    }
                }
            }
    
        }
    }
    

To download satellite assemblies on demand in Visual Basic

  1. In the Properties window for the application, click the Application tab.

  2. At the bottom of the tab page, click View Application Events.

  3. Add the following imports to the beginning of the ApplicationEvents.VB file.

    Imports System.Deployment.Application
    Imports System.Globalization
    Imports System.Threading
    
  4. Add the following code to the MyApplication class.

    Private Sub MyApplication_Startup(ByVal sender As Object, ByVal e As Microsoft.VisualBasic.ApplicationServices.StartupEventArgs) Handles Me.Startup
        Thread.CurrentThread.CurrentUICulture = New CultureInfo("ja-JP")
        GetSatelliteAssemblies(Thread.CurrentThread.CurrentUICulture.ToString())
    End Sub 
    
    Private Shared Sub GetSatelliteAssemblies(ByVal groupName As String)
        If (ApplicationDeployment.IsNetworkDeployed) Then 
    
            Dim deploy As ApplicationDeployment = ApplicationDeployment.CurrentDeployment
    
            If (deploy.IsFirstRun) Then 
                Try
                    deploy.DownloadFileGroup(groupName)
                Catch de As DeploymentException
                    ' Log error. Do not report this error to the user, because a satellite 
                    ' assembly may not exist if the user's culture and the application's 
                    ' default culture match. 
                End Try 
            End If 
        End If 
    End Sub
    

In a production environment, you will likely need to remove the line in the code examples that sets CurrentUICulture to a specific value, because client machines will have the correct value set by default. When your application runs on a Japanese client machine, for example, CurrentUICulture will be ja-JP by default. Setting it programmatically is a good way to test your satellite assemblies before you deploy your application.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.