Merge remote-tracking branch 'refs/remotes/origin/master' into Xamari…

…n.Forms

Documentation/WPF/90-DeployingPrismApplications.md

@@ -0,0 +1,88 @@
+1.  **\#!155CharTopicSummary!\#:**
+
+    Learn the deployment options for a composite WPF application – Xcopy, ClickOnce, Windows Installer.
+
+    1.  To successfully move a Prism application into production, you need to plan for deployment as part of the design process of your application. This topic covers the considerations and actions you need to perform to prepare your composite or modular application for deployment and the actions you need to take to get the application in the user's hands.
+
+<span id="DeployingSilverlightPrismApplications" class="anchor"><span id="PackagingPrismModulesasXAPFiles" class="anchor"><span id="ReducingtheDownloadSizeofYourModul" class="anchor"><span id="DeployingWPFPrismApplications" class="anchor"></span></span></span></span>Deploying WPF Prism Applications
+===========================================================================================================================================================================================================================================================================================================
+
+1.  A WPF Prism application can be composed of an executable and any number of additional DLLs. The main executable is the shell application project. Some of the additional DLLs will be the modules of the application. There may be some additional DLLs that are just shared assemblies used by the shell and modules of the application. In addition, you might have a set of resource or content files that get deployed along with the application.
+
+    To deploy a WPF Prism application, you have three choices:
+
+<!-- -->
+
+1.  "XCopy deployment"
+
+    ClickOnce deployment
+
+    Windows Installer deployment
+
+    1.  
+
+    <!-- -->
+
+    1.  "XCopy deployment" is used as a general term for manual deployment through some sort of file copy operation, which may or may not include the use of the XCOPY command-line tool. If you choose to deploy the application in this way, it is up to you to manually package the files and move them to the target computer. The application should be ready to run as long as the expected folder structure and relative locations of the shell application executable, the module DLLs, and the content files are maintained.
+
+        Usually, a more automatic means of deployment is desired to ensure that things get placed in the right location and the user has easy access to run the application. To facilitate that, you can choose to use ClickOnce or Windows Installer (.msi files), depending on what additional installation requirements exist for the application.
+
+        The decision of whether to use ClickOnce or Windows Installer is often misunderstood. ClickOnce is not intended to be a one-size-fits-all deployment technology. It is intended for applications that need a low-impact install on a client computer. If your application needs to make computer-wide changes when it is installed—such as to install drivers, integrate with other applications, install services and other things that go outside the scope of just running your executable, ClickOnce is probably not an appropriate deployment choice. However, if you have a lightweight installation on the client computer and you want to benefit from network deployment and update of your WPF application, ClickOnce can be a great choice.
+
+        To create a Windows Installer deployment package (.msi file) for your application, you have a variety of choices, including Visual Studio Setup projects, Windows Installer XML (WiX) projects, or numerous third-party installer creation products.
+
+Deploying WPF Prism Application with ClickOnce
+----------------------------------------------
+
+1.  ClickOnce is a Windows Presentation Foundation (WPF) or Windows Forms deployment mechanism that has been part of the .NET Framework since version 2.0. ClickOnce enables automatic deployment and update of WPF applications over the network from a deployment server. WPF Prism applications can use ClickOnce to get the shell, modules, and any other dependencies deployed to the client computer. The main challenge with Prism applications is that the Visual Studio publishing process for ClickOnce does not automatically include dynamically loaded modules in the published application.
+
+    Deploying a WPF application with ClickOnce is a two-step process. First, you have to publish the application from Visual Studio, and then you can deploy it to client computers. Publishing the application generates two manifests (a deployment manifest and an application manifest), and it copies the application files to a publish directory. That publish folder can then be moved to another server that may not be directly accessible from the developer computer to make the published application accessible to client computers from a known location and URL. Deploying an application to a client computer simply requires providing a URL or link that the user can navigate to. The URL points to the deployment manifest on the publishing deployment server. When that URL is loaded in the browser, ClickOnce on the client computer downloads the manifests and the application files specified by the manifests. After the files are downloaded and stored under the user profile, ClickOnce then launches the application. If subsequent updates are published to the deployment server, ClickOnce can automatically detect those updates, download, and apply them, or there are settings that allow you to detect and apply updates on demand or in the background after the application has launched.
+
+    When you publish a WPF Prism application that has dynamically loaded modules, the shell project will typically not have project references to the dynamically loaded modules. As a result, the published ClickOnce application manifest also does not include those module files, and if you deploy the application using ClickOnce, the client computer will not get the module files. To address this, you must modify the application manifest to include the module files that are not referenced by the shell application project.
+
+### ClickOnce Publishing Process
+
+1.  You can publish ClickOnce applications from Visual Studio 2013 using the Windows Software Development Kit (SDK) tool named the Manifest Generating and Editing tool (Mage) or a custom tool that uses the ClickOnce publishing APIs. Visual Studio exposes most of the capabilities needed for ClickOnce publishing. However, Visual Studio may not be available or desired for IT administrators who manage ClickOnce deployments on the server. Mage is designed to address most common administrative tasks for ClickOnce; it is a lightweight .NET Framework Windows-based application that can be given to your administrators. However, Mage requires too many detailed steps, performed in the correct order, to successfully complete common tasks such as modifying the application files listed in the application manifest. To make these tasks simpler, a custom utility is needed.
+
+    The Manifest Manager Utility sample utility demonstrates how to use the ClickOnce publishing API to manage deployment and application manifests in a simpler way. This utility is used for updating application manifest file lists and deployment manifest settings in a single user interface (UI) and its use is described in later sections in this topic for initial deployment and update of a Prism application. The Manifest Manager Utility uses APIs exposed in the **Microsoft.Build.Tasks.Deployment** namespace to load, manipulate, and save modified manifest files for a ClickOnce deployment. You can download the Manifest Manager Utility from the Prism community site on Codeplex. To learn the specific steps involved in publishing and updating a WPF Prism application that uses dynamic module loading, see the .
+
+    The following illustration shows the typical structure for a ClickOnce application publication, based on the way Visual Studio generates the deployment folders when you publish an application with ClickOnce. It includes a root folder for the application, which contains the default deployment manifest (.application file). The default deployment manifest usually points to the most recently published version when generated by Visual Studio, but it can be changed to point to whichever version the administrator chooses. The root folder also contains the Setup.exe bootstrapper, which allows you to deploy prerequisites for your application that might require an installer or executable to run before deploying the application using ClickOnce. There is then a subfolder for the application-specific files, under which you get a separate subfolder for each version that you publish. The publish version is a separate project setting and entry in the deployment manifest file for versioning the deployment as a whole, as opposed to the individual assembly versions of the contained assemblies. The publish version is used by ClickOnce to determine when there is an update available from a client that has already installed a ClickOnce application.
+
+<!-- -->
+
+1.  ![](media/image1.png)
+
+<!-- -->
+
+1.  ClickOnce publish folder structure
+
+<!-- -->
+
+1.  Under each publish version's application files folder, you have another copy of the deployment manifest (.application file) that can be used to deploy specific versions to a client computer, or it can be copied to the root folder to cause a server-side rollback to a previous version. The application executable, in addition to any dependent libraries (such as Prism module assemblies) and resource files, will also be in this folder and will be automatically suffixed by a .deploy file name extension when published by Visual Studio. This is done to simplify the file extension mappings on the publishing web server so that you don't have to allow downloads of .dll, .exe, and a myriad of other potential file types that the application is composed of.
+
+    The application manifest (.exe.manifest) file is also contained in this folder and is referenced by the deployment manifest. It contains the list of files the application is composed of with hash values per file to assist in change detection; it also contains a list of permissions required by the application to run because ClickOnce can launch applications in a partial trust AppDomain if desired.
+
+    If you manually generate or update a ClickOnce application publication using either Mage or a custom tool, you are not constrained to this folder and file structure. For any particular ClickOnce publication, the chain of dependencies includes the following:
+
+-   It includes a deployment manifest that points to the application manifest through an embedded code base URL.
+
+-   It includes an application manifest that contains relative paths to each of the application files. These files must reside in the same folder or a subfolder from where the application manifest resides.
+
+1.  
+
+<!-- -->
+
+1.  It includes the application files themselves, usually with a .deploy file name extension appended to the file name to simplify mapping these files to MIME types on the deployment server. ClickOnce automatically strips off the .deploy file name extension on the client side after the file is downloaded.
+
+### ClickOnce Deployment and Update Process
+
+1.  The actual deployment of the application to a user via ClickOnce is almost always initiated by providing a URL or hyperlink to the deployment manifest of your published application on the deployment server. The user can click the hyperlink or enter the address in a browser, and the ClickOnce deployment process is invoked. After the manifest and application files are downloaded to the client computer, the application is launched. There are ClickOnce options that allow you to install the application during the initial deployment for offline use, or you can require the user to launch the application using the link or URL every time. When you publish a new version of the application to the deployment server, ClickOnce can automatically or manually check for updates and will download and apply the update for the next time the application launches.
+
+More Information
+================
+
+1.  You can download the Manifest Manager Utility from the Prism community site on Codeplex.
+
+    To learn the specific steps involved in publishing and updating a WPF Prism application that uses dynamic module loading, see the .
+
+

Documentation/WPF/AppendixA-Glossary.md

@@ -0,0 +1,79 @@
+1.  **\#!155CharTopicSummary!\#:**
+
+    Learn the important terms used in the Prism for WPF documentation.
+
+    1.  This glossary includes definitions of important terms that appear in the Prism documentation.
+
+        **bootstrapper**. The class responsible for the initialization of an application built using the Prism Library.
+
+        **command**. A loosely coupled way for you to handle user interface (UI) actions. Commands bind a UI gesture to the logic that performs the action.
+
+        **composite application**. A composite application is composed of a number of discrete and independent modules. These components are integrated together in a host environment to form a single, seamless application.
+
+        **composite command**. A command that has multiple child commands.
+
+        **container**. Provides a layer of abstraction for the creation of objects. Dependency injection containers can reduce the dependency coupling between objects by providing the facility to instantiate instances of classes and manage their lifetime based on the configuration of the container.
+
+        **DelegateCommand**. Allows delegating the commanding handling logic to selected methods instead of requiring a handler in the code-behind. It uses .NET Framework delegates as the method of invoking a target handling method.
+
+        **EventAggregator**. A service that is primarily a container for events that allows publishers and subscribers to be decoupled so they can evolve independently. This decoupling is useful in modularized applications because new modules can be added that respond to events defined by the shell or other modules.
+
+        **modularity**. The ability to create complex applications from discrete functional units named *modules*. When you develop in a modularized fashion, you structure the application into separate modules that can be individually developed, tested, and deployed by different teams. It also helps you address separation of concerns by keeping a clean separation between the UI and business functionality.
+
+        **model**. Encapsulates the application's business logic and data.
+
+        **Model-View-ViewModel (MVVM).** The MVVM pattern helps to cleanly separate the business and presentation logic of your application from its user interface (UI). Maintaining a clean separation between application logic and UI helps to address numerous development and design issues and can make the application much easier to test, maintain, and evolve.
+
+        **module**. A logical unit of separation in the application.
+
+        **ModuleCatalog**. Defines the modules that the end user needs to run the application. The module catalog knows where the modules are located and the module's dependencies.
+
+        **ModuleManager**. The main class that manages the process of validating the module catalog, retrieving modules if they are remote, loading the modules into the application domain, and invoking the module's **Initialize** method.
+
+        **module management phases**. The phases that lead to a module being initialized. These phases are module discovery, module loading, and module initialization.
+
+        **navigation**. The process by which the application coordinates changes to its UI as a result of the user's interaction with the application, or as a result of internal application state changes.
+
+        **ViewModel-first composition**. The composition approach where the view model is logically created first, followed by the view.
+
+        **Notifications.** Provide change notifications to any data-bound controls in the view when the underlying property value changes. This is required to implement the MVVM pattern and is implemented using the BindableBase class.
+
+        **on-demand module**. A module that is retrieved and initialized only when it is explicitly requested by the application.
+
+        **region**. A named location that you can use to define where a view will appear. Modules can locate and add content to a region in the layout without exact knowledge of how and where the region is visually displayed. This allows the appearance and layout to change without affecting the modules that add the content to the layout.
+
+        **RegionContext**. A technique that can be used to share context between a parent view and child views that are hosted in a region. The **RegionContext** can be set through code or by using data binding XAML.
+
+        **RegionManager**. The class responsible for maintaining a collection of regions and creating new regions for controls. The **RegionManager** finds an adapter mapped to a WPF control and associates a new region to that control. The **RegionManager** also supplies the attached property that can be used for simple region creation from XAML.
+
+        **Separated Presentation pattern**. Pattern used to implement views, which separates presentation and business logic from the UI. Using a separated presentation allows presentation and business logic to be tested independently of the UI, makes it easier to maintain code, and increases re-use opportunities.
+
+        **shell**. The main window of a WPF application where the primary UI content is contained.
+
+        **scoped region**. Regions that belong to a particular region scope. The region scope is delimited by a parent view and includes all the child views of the parent view.
+
+        **service**. A service provides functionality to other modules in a loosely coupled way through an interface and is often a singleton.
+
+        **state-based navigation**. Navigation accomplished via state changes to existing controls in the visual tree.
+
+        **UI composition**. The act of building an interface by composing it from discrete views at run time, likely from separate modules.
+
+    <!-- -->
+
+    1.  **view**. The main unit of UI construction within a composite UI application. The view encapsulates the UI and UI logic that you would like to keep as decoupled as possible from other parts of the application. You can define a view as a user control, data template, or even a custom control.
+
+        **view-based navigation**. Navigation accomplished via the addition or removal of elements from the visual tree.
+
+    <!-- -->
+
+    1.  **view-first composition**. The composition approach where the view is logically created first, followed by the view model or presenter on which it depends.
+
+        **view discovery**. A way to add, show, or remove views in a region by associating the type of a view with a region name. Whenever a region with that name displays, the registered views will be automatically created and added to the region.
+
+        **view injection**. A way to add, show, or remove views in a region by adding or removing instances of a view to a region. The code interacting with the region does not have direct knowledge of how the region will handle displaying the view.
+
+        **view model**. Encapsulates the presentation logic and state for the view. It is responsible for coordinating the view's interaction with any model classes that are required.
+
+        **view model location**. Locates and instantiates view models and associating to their respective views typically by using a convention base approach.
+
+