Download as pdf or txt
Download as pdf or txt
You are on page 1of 70

Introducing .

NET MAUI: Build and


Deploy Cross-platform Applications
Using C# and .NET Multi-platform App
UI 1st Edition Shaun Lawrence
Visit to download the full and correct content document:
https://ebookmass.com/product/introducing-net-maui-build-and-deploy-cross-platform
-applications-using-c-and-net-multi-platform-app-ui-1st-edition-shaun-lawrence/
More products digital (pdf, epub, mobi) instant
download maybe you interests ...

Designing Applications for Google Cloud Platform:


Create and Deploy Applications Using Java Ashutosh
Shashi

https://ebookmass.com/product/designing-applications-for-google-
cloud-platform-create-and-deploy-applications-using-java-
ashutosh-shashi/

Simple and Efficient Programming with C#: Skills to


Build Applications with Visual Studio and .NET 2nd
Edition Vaskaran Sarcar

https://ebookmass.com/product/simple-and-efficient-programming-
with-c-skills-to-build-applications-with-visual-studio-and-
net-2nd-edition-vaskaran-sarcar/

Simple and Efficient Programming with C# : Skills to


Build Applications with Visual Studio and .NET 2nd
Edition Vaskaran Sarcar

https://ebookmass.com/product/simple-and-efficient-programming-
with-c-skills-to-build-applications-with-visual-studio-and-
net-2nd-edition-vaskaran-sarcar-2/

Multi-rotor Platform Based UAV Systems 1st Edition


Franck Cazaurang

https://ebookmass.com/product/multi-rotor-platform-based-uav-
systems-1st-edition-franck-cazaurang/
Pro C# 7: With .NET and Core 8th ed. Edition

https://ebookmass.com/product/pro-c-7-with-net-and-core-8th-ed-
edition/

Platform Urbanism: Negotiating Platform Ecosystems in


Connected Cities 1st ed. 2020 Edition Sarah Barns

https://ebookmass.com/product/platform-urbanism-negotiating-
platform-ecosystems-in-connected-cities-1st-ed-2020-edition-
sarah-barns/

Nothing But Net 1st Edition Mark Mahaney

https://ebookmass.com/product/nothing-but-net-1st-edition-mark-
mahaney/

Flame Game Development: Your Guide to Creating Cross-


Platform Games in 2D Using Flame Engine in Flutter 3
1st Edition Andrés Cruz Yoris

https://ebookmass.com/product/flame-game-development-your-guide-
to-creating-cross-platform-games-in-2d-using-flame-engine-in-
flutter-3-1st-edition-andres-cruz-yoris/

Flame Game Development: Your Guide to Creating Cross-


platform Games in 2D Using Flame Engine in Flutter 3
Andrés Cruz Yoris

https://ebookmass.com/product/flame-game-development-your-guide-
to-creating-cross-platform-games-in-2d-using-flame-engine-in-
flutter-3-andres-cruz-yoris/
Introducing
.NET MAUI
Build and Deploy
Cross-­platform Applications
Using C# and .NET
Multi-platform App UI

Shaun Lawrence
Introducing .NET MAUI: Build and Deploy Cross-platform Applications
Using C# and .NET Multi-platform App UI
Shaun Lawrence
St Ives, UK

ISBN-13 (pbk): 978-1-4842-9233-4 ISBN-13 (electronic): 978-1-4842-9234-1


https://doi.org/10.1007/978-1-4842-9234-1

Copyright © 2023 by Shaun Lawrence


This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or
part of the material is concerned, specifically the rights of translation, reprinting, reuse of
illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way,
and transmission or information storage and retrieval, electronic adaptation, computer software,
or by similar or dissimilar methodology now known or hereafter developed.
Trademarked names, logos, and images may appear in this book. Rather than use a trademark
symbol with every occurrence of a trademarked name, logo, or image we use the names, logos,
and images only in an editorial fashion and to the benefit of the trademark owner, with no
intention of infringement of the trademark.
The use in this publication of trade names, trademarks, service marks, and similar terms, even if
they are not identified as such, is not to be taken as an expression of opinion as to whether or not
they are subject to proprietary rights.
While the advice and information in this book are believed to be true and accurate at the date of
publication, neither the authors nor the editors nor the publisher can accept any legal
responsibility for any errors or omissions that may be made. The publisher makes no warranty,
express or implied, with respect to the material contained herein.
Managing Director, Apress Media LLC: Welmoed Spahr
Acquisitions Editor: Joan Murray
Development Editor: Laura Berendson
Editorial Assistant: Gryffin Winkler
Copy Editor: Mary Behr
Cover image designed by mrsiraphol through Freepik (www.freepik.com)
Distributed to the book trade worldwide by Springer Science+Business Media LLC, 1 New York
Plaza, Suite 4600, New York, NY 10004. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail
orders-ny@springer-sbm.com, or visit www.springeronline.com. Apress Media, LLC is a
California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc
(SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation.
For information on translations, please e-mail booktranslations@springernature.com; for reprint,
paperback, or audio rights, please e-mail bookpermissions@springernature.com.
Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook
versions and licenses are also available for most titles. For more information, reference our
Print and eBook Bulk Sales web page at www.apress.com/bulk-sales.
Any source code or other supplementary material referenced by the author in this book is
available to readers on GitHub using this link: https://github.com/Apress/Introducing-MAUI.
Printed on acid-free paper
Table of Contents
About the Author��������������������������������������������������������������������������������xv

About the Technical Reviewer����������������������������������������������������������xvii

Acknowledgments�����������������������������������������������������������������������������xix

Introduction���������������������������������������������������������������������������������������xxi

Part I: Getting to Know .NET MAUI�����������������������������������������������1


Chapter 1: Introduction to .NET MAUI���������������������������������������������������3
What is .NET MAUI?����������������������������������������������������������������������������������������������3
Digging a Bit Deeper����������������������������������������������������������������������������������������5
Where Did It Come From?��������������������������������������������������������������������������������6
How It Differs From the Competition���������������������������������������������������������������7
Why Use .NET MAUI?���������������������������������������������������������������������������������������������8
Supported Platforms����������������������������������������������������������������������������������������8
Code Sharing���������������������������������������������������������������������������������������������������9
Developer Freedom���������������������������������������������������������������������������������������10
Community����������������������������������������������������������������������������������������������������10
Fast Development Cycle��������������������������������������������������������������������������������10
Performance��������������������������������������������������������������������������������������������������11
Strong Commercial Offerings������������������������������������������������������������������������12

iii
Table of Contents

Limitations of .NET MAUI������������������������������������������������������������������������������������13


No Web Assembly (WASM) Support���������������������������������������������������������������13
No Camera API�����������������������������������������������������������������������������������������������13
Apps Won’t Look Identical on Each Platform�������������������������������������������������14
Lack of Media Playback Out of the Box���������������������������������������������������������14
The Glass Is Half Full, Though�����������������������������������������������������������������������������14
How to Build .NET MAUI Applications������������������������������������������������������������������15
Visual Studio��������������������������������������������������������������������������������������������������15
Summary������������������������������������������������������������������������������������������������������������17

Chapter 2: Building Our First application�������������������������������������������19


Setting Up Your Environment������������������������������������������������������������������������������19
macOS�����������������������������������������������������������������������������������������������������������19
Windows��������������������������������������������������������������������������������������������������������27
Visual Studio to macOS���������������������������������������������������������������������������������28
Troubleshooting Installation Issues���������������������������������������������������������������������32
.NET MAUI Workload Is Missing���������������������������������������������������������������������32
Creating Your First Application����������������������������������������������������������������������������33
Creating in Visual Studio�������������������������������������������������������������������������������33
Creating in the Command Line����������������������������������������������������������������������37
Building and Running Your First Application�������������������������������������������������������38
Getting to Know Your Application������������������������������������������������������������������������41
WidgetBoard��������������������������������������������������������������������������������������������������41
Summary������������������������������������������������������������������������������������������������������������42
Source Code��������������������������������������������������������������������������������������������������43

iv
Table of Contents

Chapter 3: The Fundamentals of .NET MAUI���������������������������������������45


Project Structure�������������������������������������������������������������������������������������������������45
/Platforms/ Folder������������������������������������������������������������������������������������������48
/Resources/ Folder����������������������������������������������������������������������������������������51
Where To Begin?�������������������������������������������������������������������������������������������������56
Generic Host Builder�������������������������������������������������������������������������������������������56
What Is Dependency Injection?���������������������������������������������������������������������57
Registering Dependencies�����������������������������������������������������������������������������60
Application Lifecycle�������������������������������������������������������������������������������������������62
Application States�����������������������������������������������������������������������������������������62
Lifecycle Events���������������������������������������������������������������������������������������������64
Handling Lifecycle Events������������������������������������������������������������������������������65
Cross-Platform Mappings to Platform Lifecycle Events��������������������������������66
Platform-Specific Lifecycle Events����������������������������������������������������������������67
Summary������������������������������������������������������������������������������������������������������������72

Chapter 4: An Architecture to Suit You�����������������������������������������������75


A Measuring Stick�����������������������������������������������������������������������������������������������75
Prerequisites�������������������������������������������������������������������������������������������������������76
Model View ViewModel (MVVM)��������������������������������������������������������������������������77
Model�������������������������������������������������������������������������������������������������������������78
View���������������������������������������������������������������������������������������������������������������79
ViewModel�����������������������������������������������������������������������������������������������������80
Model View Update (MVU)�����������������������������������������������������������������������������������83
Getting Started with Comet���������������������������������������������������������������������������84
Adding Your MVU Implementation�����������������������������������������������������������������84

v
Table of Contents

XAML vs. C# Markup�������������������������������������������������������������������������������������������86


Plain C#���������������������������������������������������������������������������������������������������������87
C# Markup�����������������������������������������������������������������������������������������������������88
Chosen Architecture for This Book����������������������������������������������������������������������89
Adding the ViewModels���������������������������������������������������������������������������������90
Adding Views�������������������������������������������������������������������������������������������������96
Viewing Your Widget��������������������������������������������������������������������������������������99
MVVM Enhancements����������������������������������������������������������������������������������101
Summary����������������������������������������������������������������������������������������������������������105
Source Code������������������������������������������������������������������������������������������������107

Part II: User Interface��������������������������������������������������������������109


Chapter 5: User Interface Essentials������������������������������������������������111
Prerequisites�����������������������������������������������������������������������������������������������������111
Models���������������������������������������������������������������������������������������������������������111
Pages�����������������������������������������������������������������������������������������������������������113
ViewModels�������������������������������������������������������������������������������������������������114
App Icons����������������������������������������������������������������������������������������������������������116
Adding Your Own Icon����������������������������������������������������������������������������������116
Platform Differences������������������������������������������������������������������������������������117
Splash Screen���������������������������������������������������������������������������������������������������118
XAML�����������������������������������������������������������������������������������������������������������������119
Dissecting a XAML File��������������������������������������������������������������������������������120
Building Your First XAML Page��������������������������������������������������������������������122
Layouts�������������������������������������������������������������������������������������������������������������124
AbsoluteLayout��������������������������������������������������������������������������������������������124
FlexLayout���������������������������������������������������������������������������������������������������126
Grid��������������������������������������������������������������������������������������������������������������128
HorizontalStackLayout���������������������������������������������������������������������������������131
vi
Table of Contents

VerticalStackLayout�������������������������������������������������������������������������������������132
Data Binding�����������������������������������������������������������������������������������������������������135
Binding��������������������������������������������������������������������������������������������������������136
Applying the Remaining Bindings����������������������������������������������������������������140
MultiBinding������������������������������������������������������������������������������������������������141
Command����������������������������������������������������������������������������������������������������144
Compiled Bindings���������������������������������������������������������������������������������������147
Shell������������������������������������������������������������������������������������������������������������������148
ShellContent������������������������������������������������������������������������������������������������149
Navigation���������������������������������������������������������������������������������������������������150
Flyout�����������������������������������������������������������������������������������������������������������154
Tabs�������������������������������������������������������������������������������������������������������������160
Search���������������������������������������������������������������������������������������������������������160
Taking Your Application for a Spin���������������������������������������������������������������������161
Summary����������������������������������������������������������������������������������������������������������163
Source Code������������������������������������������������������������������������������������������������164
Extra Assignment����������������������������������������������������������������������������������������������164

Chapter 6: Creating Our Own Layout������������������������������������������������165


Placeholder�������������������������������������������������������������������������������������������������������166
ILayoutManager������������������������������������������������������������������������������������������������168
BoardLayout������������������������������������������������������������������������������������������������������169
BoardLayout.xaml����������������������������������������������������������������������������������������169
BoardLayout.xaml.cs�����������������������������������������������������������������������������������172
FixedLayoutManager�����������������������������������������������������������������������������������������177
Accepting the Number of Rows and Columns for a Board��������������������������179
Providing Tap/Click Support Through a Command��������������������������������������181
Building the Board Layout���������������������������������������������������������������������������182
Setting the Correct Row/Column Position for Each Widget�������������������������185

vii
Table of Contents

Using Your Layout���������������������������������������������������������������������������������������������187


Adding a Factory That Will Create Instances of Your Widgets���������������������187
WidgetTemplateSelector������������������������������������������������������������������������������193
Updating FixedBoardPageViewModel����������������������������������������������������������194
Finally Using the Layout������������������������������������������������������������������������������196
Summary����������������������������������������������������������������������������������������������������������197
Source Code������������������������������������������������������������������������������������������������198
Extra Assignment����������������������������������������������������������������������������������������������198

Chapter 7: Accessibility��������������������������������������������������������������������199
What Is Accessibility?���������������������������������������������������������������������������������������199
Why Make Your Applications Accessible?���������������������������������������������������������200
What to Consider When Making Your Applications Accessible��������������������������200
How to Make Your Application Accessible��������������������������������������������������������201
Screen Reader Support�������������������������������������������������������������������������������201
Suitable Contrast�����������������������������������������������������������������������������������������208
Dynamic Text Sizing�������������������������������������������������������������������������������������210
Testing Your Application’s Accessibility�������������������������������������������������������������215
Android��������������������������������������������������������������������������������������������������������215
iOS���������������������������������������������������������������������������������������������������������������215
macOS���������������������������������������������������������������������������������������������������������216
Windows������������������������������������������������������������������������������������������������������216
Accessibility Checklist��������������������������������������������������������������������������������������216
Summary����������������������������������������������������������������������������������������������������������218
Source Code������������������������������������������������������������������������������������������������219
Extra Assignment����������������������������������������������������������������������������������������������219

viii
Table of Contents

Chapter 8: Advanced UI Concepts�����������������������������������������������������221


Adding the Ability to Add a Widget to a Board���������������������������������������������������221
Possible Ways of Achieving Your Goal���������������������������������������������������������222
The Chosen Approach����������������������������������������������������������������������������������224
Styling���������������������������������������������������������������������������������������������������������������230
Examining the Default Styles�����������������������������������������������������������������������232
Creating a Style�������������������������������������������������������������������������������������������234
AppThemeBinding���������������������������������������������������������������������������������������236
Further Reading�������������������������������������������������������������������������������������������236
Triggers�������������������������������������������������������������������������������������������������������������237
Creating a DataTrigger���������������������������������������������������������������������������������238
EnterActions and ExitActions�����������������������������������������������������������������������239
Creating a TriggerAction������������������������������������������������������������������������������240
Further Reading�������������������������������������������������������������������������������������������242
Animations���������������������������������������������������������������������������������������������������242
Basic Animations�����������������������������������������������������������������������������������������243
Combining Basic Animations�����������������������������������������������������������������������245
Cancelling Animations���������������������������������������������������������������������������������246
Easings��������������������������������������������������������������������������������������������������������246
Complex Animations������������������������������������������������������������������������������������247
Combining Triggers and Animations�����������������������������������������������������������������252
Summary����������������������������������������������������������������������������������������������������������254
Source Code������������������������������������������������������������������������������������������������255
Extra Assignment����������������������������������������������������������������������������������������������255
Animate the BoxView Overlay����������������������������������������������������������������������255
Animate the New Widget�����������������������������������������������������������������������������255

ix
Table of Contents

Part III: Behind the Scenes������������������������������������������������������257


Chapter 9: Local Data�����������������������������������������������������������������������259
What Is Local Data?������������������������������������������������������������������������������������������259
File System�������������������������������������������������������������������������������������������������������260
Cache Directory�������������������������������������������������������������������������������������������260
App Data Directory��������������������������������������������������������������������������������������261
Database�����������������������������������������������������������������������������������������������������������261
Repository Pattern���������������������������������������������������������������������������������������262
SQLite����������������������������������������������������������������������������������������������������������270
LiteDB����������������������������������������������������������������������������������������������������������278
Database Summary�������������������������������������������������������������������������������������285
Application Settings (Preferences)��������������������������������������������������������������������285
What Can Be Stored in Preferences?����������������������������������������������������������286
Setting a Value in Preferences��������������������������������������������������������������������286
Getting a Value in Preferences��������������������������������������������������������������������288
Checking if a Key Exists in Preferences������������������������������������������������������290
Removing a Preference�������������������������������������������������������������������������������291
Secure Storage�������������������������������������������������������������������������������������������������291
Storing a Value Securely������������������������������������������������������������������������������291
Reading a Secure Value�������������������������������������������������������������������������������292
Removing a Secure Value����������������������������������������������������������������������������292
Platform specifics����������������������������������������������������������������������������������������293
Viewing the Result��������������������������������������������������������������������������������������������295
Summary����������������������������������������������������������������������������������������������������������296
Source Code������������������������������������������������������������������������������������������������297
Extra Assignment����������������������������������������������������������������������������������������������297

x
Table of Contents

Chapter 10: Remote Data������������������������������������������������������������������299


What Is Remote Data?��������������������������������������������������������������������������������������299
Considerations When Handling Remote Data����������������������������������������������300
Webservices������������������������������������������������������������������������������������������������������302
The Open Weather API���������������������������������������������������������������������������������302
Adding Some State��������������������������������������������������������������������������������������319
Simplifying Webservice Access������������������������������������������������������������������������326
Prebuilt Libraries�����������������������������������������������������������������������������������������327
Code Generation Libraries���������������������������������������������������������������������������327
Further Reading������������������������������������������������������������������������������������������������329
Polly�������������������������������������������������������������������������������������������������������������329
StateContainer from CommunityToolkit.Maui����������������������������������������������330
Summary����������������������������������������������������������������������������������������������������������330
Source Code������������������������������������������������������������������������������������������������331
Extra Assignment����������������������������������������������������������������������������������������������331
TODO Widget������������������������������������������������������������������������������������������������331
Quote of the Day Widget������������������������������������������������������������������������������332
NASA Space Image of the Day Widget���������������������������������������������������������332

Part IV: Utilizing the platforms������������������������������������������������333


Chapter 11: Getting Specific�������������������������������������������������������������335
.NET MAUI Essentials����������������������������������������������������������������������������������������335
Permissions�������������������������������������������������������������������������������������������������336
Using the Geolocation API����������������������������������������������������������������������������341
Configuring Platform-Specific Components������������������������������������������������346
Platform-Specific API Access����������������������������������������������������������������������������352
Platform-Specific Code with Compiler Directives���������������������������������������352
Platform-Specific Code in Platform Folders������������������������������������������������354

xi
Table of Contents

Overriding the Platform-Specific UI������������������������������������������������������������������355


OnPlatform��������������������������������������������������������������������������������������������������355
Handlers������������������������������������������������������������������������������������������������������358
Summary����������������������������������������������������������������������������������������������������������361
Source Code������������������������������������������������������������������������������������������������362
Extra Assignment����������������������������������������������������������������������������������������������362
Barometer Widget����������������������������������������������������������������������������������������362
Geocoding Lookup���������������������������������������������������������������������������������������363

Chapter 12: Testing���������������������������������������������������������������������������365


Unit Testing�������������������������������������������������������������������������������������������������������365
Unit Testing in .NET MAUI����������������������������������������������������������������������������366
Adding Your Own Unit Tests�������������������������������������������������������������������������368
Testing Your View Models����������������������������������������������������������������������������372
Testing Asynchronous Operations���������������������������������������������������������������374
Testing Your Views���������������������������������������������������������������������������������������380
Device Testing���������������������������������������������������������������������������������������������������382
Creating a Device Test Project���������������������������������������������������������������������383
Adding a Device-Specific Test���������������������������������������������������������������������383
Running Device-Specific Tests��������������������������������������������������������������������384
Snapshot Testing�����������������������������������������������������������������������������������������������386
Snapshot Testing Your Application���������������������������������������������������������������387
Passing Thoughts����������������������������������������������������������������������������������������390
Looking to the Future����������������������������������������������������������������������������������������390
Summary����������������������������������������������������������������������������������������������������������391
Source Code������������������������������������������������������������������������������������������������391

xii
Table of Contents

Chapter 13: Lets Get Graphical���������������������������������������������������������393


.NET MAUI Graphics������������������������������������������������������������������������������������������393
Drawing on the Screen��������������������������������������������������������������������������������394
Further Reading�������������������������������������������������������������������������������������������397
Building a Sketch Widget����������������������������������������������������������������������������������397
Creating the SketchWidgetViewModel��������������������������������������������������������397
Representing a User Interaction������������������������������������������������������������������398
Creating the SketchWidgetView������������������������������������������������������������������399
Registering Your Widget������������������������������������������������������������������������������404
Taking Your Widget for a Test Draw�������������������������������������������������������������404
Summary����������������������������������������������������������������������������������������������������������405
Source Code������������������������������������������������������������������������������������������������405
Extra Assignment����������������������������������������������������������������������������������������������406

Part V: Finishing Our Application���������������������������������������������407


Chapter 14: Releasing Our Application���������������������������������������������409
Distributing Your Application�����������������������������������������������������������������������������409
Android��������������������������������������������������������������������������������������������������������410
iOS���������������������������������������������������������������������������������������������������������������412
macOS���������������������������������������������������������������������������������������������������������415
Windows������������������������������������������������������������������������������������������������������416
Things to Consider��������������������������������������������������������������������������������������������416
Following Good Practices����������������������������������������������������������������������������416
Performance������������������������������������������������������������������������������������������������418
Linking���������������������������������������������������������������������������������������������������������421
Crashes/Analytics����������������������������������������������������������������������������������������422
Obfuscation�������������������������������������������������������������������������������������������������424
Distributing Test Versions����������������������������������������������������������������������������������426
Summary����������������������������������������������������������������������������������������������������������427
xiii
Table of Contents

Chapter 15: Conclusion���������������������������������������������������������������������429


Looking at the Final Product�����������������������������������������������������������������������������429
Taking the Project Further���������������������������������������������������������������������������431
Useful Resources����������������������������������������������������������������������������������������������432
StackOverflow���������������������������������������������������������������������������������������������433
GitHub����������������������������������������������������������������������������������������������������������433
YouTube�������������������������������������������������������������������������������������������������������433
Social Media������������������������������������������������������������������������������������������������434
Yet More Goodness��������������������������������������������������������������������������������������434
Looking Forward�����������������������������������������������������������������������������������������������434
Upgrading from Xamarin.Forms������������������������������������������������������������������435
Comet����������������������������������������������������������������������������������������������������������435
Testing���������������������������������������������������������������������������������������������������������436

Index�������������������������������������������������������������������������������������������������437

xiv
About the Author
Shaun Lawrence is an experienced software
engineer who has been specializing in building
mobile and desktop applications for the past
15 years. He is a recognized Microsoft MVP in
Development Technologies; his work helps
the community learn and build with Xamarin
Forms, the predecessor to .NET MAUI. His
recent discovery of the value he can add by
sharing his experience with others has thrust
him on to the path of wanting to find any way possible to continue to do so.
Shaun actively maintains several open-source projects within the .NET
community. A key project for the scope of this book is the .NET MAUI
Community Toolkit where he predominantly focuses on building good
quality documentation for developers to consume. Shaun lives in the
United Kingdom with his wife, two children, and their dog.
Shaun can be found on Twitter @Bijington, on his blog at
https://blog.bijington.com, or on LinkedIn at ­www.linkedin.com/in/
shaun-lawrence-53a0099/.

xv
About the Technical Reviewer
Gerald Versluis is a Senior Software Engineer
at Microsoft working on .NET MAUI. Since
2009 Gerald has been working on a variety
of projects, ranging from front end to back
end and anything in between that involves
Azure, ASP.NET, and all kinds of other .NET
technologies. At some point he fell in love with
cross-platform and mobile development with
Xamarin. Since then he has become an active
community member, writing, tweeting, and presenting about all things
tech. Gerald can be found on Twitter @jfversluis, blogging at https://
blog.verslu.is, or on his YouTube channel at https://youtube.com/
@jfversluis.

xvii
Acknowledgments
I have a number of people that I would like to thank for their assistance.
Firstly, Dan: Your assistance in both reviewing my content and also
talking through each of my worries and ideas definitely encouraged me
to write.
Secondly, Gerald: You have been fundamental from start to finish. You
encouraged me to accept this project, helped me with decisions, reviewed
the content, and provided fantastic guidance throughout!
Thirdly, the team at Apress: From Joan for initially reaching out to me
in order to present this opportunity, to the rest of the team of Jill, Gryffin,
and Laura for answering all of my questions and guiding me through this
process.
Finally, my family—my wife, Levinia, daughters Zoey and Hollie, and
dog, Soco: Without your encouragement I would not have taken the leap to
embark upon this writing journey. I am so grateful for all your help and the
sacrifices made to help get me over the line.

xix
Introduction
Welcome to Introducing .NET MAUI.
This book is for developers who are new to .NET MAUI and cross-­platform
development. You should have basic knowledge of C# but require no prior
knowledge of using .NET MAUI. The content ranges from beginner through
to more advanced topics and is therefore tailored to meet a wide range of
experiences.
This book provides an in-depth explanation of each key concept in
.NET MAUI, and you will use these concepts in practical examples while
building a cross-platform application. The content has been designed
to primarily flow with the building of this application; however, there
is a secondary theme that involves grouping as many related concepts
as possible. The idea behind this is to both learn as you go and also to
have content that closely resembles reference information, which makes
returning to this book as easy as possible.
All code examples in this book, unless otherwise stated, are applied
directly to the application you are building. Once key concepts have been
established, the book will offer improvements or alternatives to simplify
your life as you build production-worthy applications. The book does not
rely upon these simplifications as part of the practical examples and the
reason for this is simple: I strongly believe that you need to understand the
concepts before you start to use them.
Finally, all chapters that involve adding code into the application
project contain a link to the resulting source code. This is to show the final
product and for you to use as a comparison if anything goes wrong during
your building of the application.

xxi
CHAPTER 1

Introduction to .NET
MAUI
In this chapter, you will gain an understanding of what exactly .NET
MAUI is, how it differs from other frameworks, and what it offers you as a
developer wishing to build a cross-platform application that can run on
both mobile and desktop environments. I will also cover the reasons why
you should consider it for your next project by weighing the possibilities
and limitations of the framework as well as the rich array of tooling
options.

What is .NET MAUI?


.NET Multi-platform App UI, or .NET MAUI for short, is a cross-­
platform framework that allows developers to build mobile and desktop
applications written in C# and XAML. It allows developers to target both
mobile (Android and iOS) and desktop (macOS and Windows) platforms
from a single codebase. Figure 1-1 shows the platforms officially supported
by .NET MAUI and Microsoft.

© Shaun Lawrence 2023 3


S. Lawrence, Introducing .NET MAUI, https://doi.org/10.1007/978-1-4842-9234-1_1
Chapter 1 Introduction to .NET MAUI

Figure 1-1. .NET MAUI platform support

.NET MAUI provides a single API that allows developers to write once
and run anywhere. When building a .NET MAUI application, you write
code that interacts with this single cross-platform API and .NET MAUI
provides the bridge between your code and the platform-specific layer.
If you take a look inside the prism in Figure 1-1, you can start to
understand the components that .NET MAUI both uses and offers.
Figure 1-2 shows how an Android application is compiled.

Figure 1-2. Interacting with .NET MAUI APIs

Of course, there will be times when you need to directly access a


platform feature. .NET MAUI also provides enough flexibility that you can
achieve this by interacting directly with the platform-specific APIs:

• .NET for Android

• .NET for iOS

4
Chapter 1 Introduction to .NET MAUI

• .NET for macOS

• Windows UI Library (WinUI) 3

Figure 1-3 shows how the code bypasses the .NET MAUI APIs and
interacts directly with the .NET for Android APIs.

Figure 1-3. Interacting with platform-specific APIs

Digging a Bit Deeper


There are some extra steps that the tooling will perform under the hood
to get your application built and ultimately ready for use on each of the
possible platforms.
When building a .NET application, even if it is not using .NET MAUI,
you will very likely hear the term BCL, which is short for the base class
library. This is the foundation of all .NET applications, and in the same way
that .NET MAUI abstracts away the platforms you wish to build for, the BCL
abstracts away what that platform implements when your application runs.
To run your application on your desired platform, you need a .NET
runtime. For Android, iOS, and macOS, this is the Mono runtime. The
Mono runtime provides the ability to run .NET code on many different
platforms. For Windows, this is Win32. Each of these runtimes provide
the functionality required for the BCL and therefore a consistent working
environment across all supported platforms.

5
Chapter 1 Introduction to .NET MAUI

I like to think of the BCL as the contract between what we are


compiling against and what we are running that compiled code with.
Figure 1-4 shows all of the layers involved in compiling and running a
.NET MAUI application.

Figure 1-4. The full breakdown

To continue with the example of building for Android in the previous


diagrams and taking note of the diagram in Figure 1-4, the following can
be said:
Your code is compiled against .NET MAUI, .NET for Android and the
base class library. It then runs on the Mono runtime, which provides a
full implementation of the base class library on the Android platform.
Looking at the above statement, you can replace the parts that are
platform specific with another platform (e.g., swapping Android for iOS)
and the statement will still be true.

Where Did It Come From?


.NET MAUI is the evolution of Xamarin.Forms, which itself has a rich
history of providing developers with a great way to build cross-platform
applications. Of course, no framework is perfect, and Xamarin.Forms
certainly had its limitations. Thankfully the team at Microsoft decided

6
Chapter 1 Introduction to .NET MAUI

to take the pragmatic approach of taking a step back and evaluating all
the pain points that existed for themselves as maintainers and (more
importantly) for us as developers using the framework.
Not only do we therefore gain improvements from the Xamarin
framework as part of this evolution, but we also get all the goodies that
come with .NET such as powerful built-in dependency injection, better
performance, and other topics that I will touch on throughout this book.
This makes me believe that this mature cross-platform framework has
finally become a first-class citizen of the .NET and Microsoft ecosystems. I
guess the clue is in the first part of its new name.
On the topic of its name, .NET MAUI implies that it is a UI framework,
and while this is true, this is not all that the framework has to offer.
Through the .NET and the .NET MAUI platform APIs, we are provided with
ways of achieving common application tasks such as file access, accessing
media from the device gallery, using the accelerometer, and more. The
.NET MAUI platform APIs were previously known as Xamarin Essentials,
so if you are coming in with some Xamarin Forms experience, they
should feel familiar. I will touch on much more of this functionality as you
progress through this book.

How It Differs From the Competition


.NET MAUI provides its own controls (for example, a Button) and then
maps them to the relevant implementation on each platform. To continue
with the example of a button, this is a UIButton from UIKit on iOS and
macOS, an AppCompatButton from AndroidX.AppCompat.Widget on
Android, and a Button from Microsoft.UI.Xaml.Controls on Windows.
This gives a great level of coverage in terms of providing a common
implementation that works across all platforms. With the introduction of
the .NET MAUI handler architecture (which will we be looking at in more
detail in Chapter 11) we truly gain the power to tweak the smallest of
implementation details on a per-platform basis. This is especially useful

7
Chapter 1 Introduction to .NET MAUI

when the common API provided by .NET MAUI may be limited down to
the least amount of crossover between each platform and doesn’t provide
everything we need. It is worth noting that your application will render
differently on each platform as it utilizes the platform specific controls and
therefore their look and feel.
Other frameworks such as Flutter opt to render their own types directly
rather than mapping across to the implementations provided by each
platform. These frameworks provide a common look and feel across each
platform. This is a hotly contested topic but I personally believe that making
applications fit in with the platform they are running on is a big benefit.

Why Use .NET MAUI?


There are several reasons why you should consider using .NET MAUI for
your next application: a large number of supported platforms, increased
code sharing capabilities, an emphasis on allowing developers to build
applications that fit their style, great performance, and many more. Let’s
take a look at them.

Supported Platforms
.NET MAUI provides official support for all of the following platforms:

• Android 5.0 (API level 21) and above

• iOS 11.0 and above

• macOS 10.15 and above (using Mac Catalyst) **

• Windows desktop

** MacCatalyst allows native Mac apps to be built and share code with
iPad apps. This is an Apple technology that allows developers to shared code
between Mac and iPad. For further reference, go to the Apple documentation
at https://developer.apple.com/mac-catalyst/.

8
Chapter 1 Introduction to .NET MAUI

.NET MAUI provides community-driven support for

• Tizen: The implementation is provided by Samsung.

I thoroughly recommend checking out the documented list of supported


platforms in case it has changed since the time of writing. The list can be found
at https://learn.microsoft.com/dotnet/maui/supported-platforms.

Code Sharing
A fundamental goal of all cross-platform frameworks is to enable
developers to focus on achieving their main goals by reducing the effort
required to support multiple platforms. This is achieved by sharing
common code across all platforms. Where I believe .NET MAUI excels over
alternative frameworks is in the first four characters of its name; Microsoft
has pushed hard to produce a single .NET that can run anywhere.
Being a full stack developer myself, I typically need to work on web-­
based back ends as well as mobile applications, .NET allows me to write
code that can be compiled into a single library. This library can then be
shared between the web and client applications, further increasing the
code sharing possibilities and ultimately reducing the maintenance effort.
I have given talks based on a mobile game (www.superwordsearch.
com) I built using Xamarin.Forms, where I boasted that we were able to
write 96% of our code in our shared project. I have not yet converted this
across to .NET MAUI; however, initial investigations show that this number
will only increase.
There are further possibilities for sharing code between web and client,
such as the use of .NET MAUI Blazor, which provides the use of web-based
technologies inside a .NET MAUI application. While I won’t be covering
.NET MAUI Blazor in detail in this book, Microsoft does provide some
really great documentation and guides on what it is and how to build your
first application with the technology at ­https://learn.microsoft.com/
aspnet/core/blazor/hybrid/tutorials/maui.

9
Chapter 1 Introduction to .NET MAUI

Developer Freedom
.NET MAUI offers many ways to build the same thing. Where Xamarin.
Forms was largely designed to support a specific application architecture
(such as MVVM, which I will talk all about in Chapter 4), .NET MAUI is
different. One key benefit of the rewrite by the team at Microsoft is it now
allows the use of other architectures such as MVU (Chapter 4). This allows
us as developers to build applications that suit our preferences, from
different architectural styles to different ways of building UIs and even
different ways of styling an application.

Community
Xamarin has always had a wonderful community. From bloggers to open-­
source maintainers, there is a vast amount of information and useful
packages available to help any developer build a great mobile application.
One thing that has really struck me is the number of Microsoft employees
who are part of this community; they are clearly passionate about the
technology and dedicate their own free time to contributing to this
community. The evolution to .NET MAUI brings this community with it.

Fast Development Cycle


.NET MAUI offers two great ways to boost a developer’s productivity.

.NET Hot Reload


.NET Hot Reload allows you to modify your managed source code while
the application is running, without the need to manually pause or hit a
breakpoint. Then, your code edits can be applied to your running app
without the need to recompile. It is worth noting that this feature is not
specific to .NET MAUI but is yet another great example of all the goodness
that comes with the framework being part of the .NET ecosystem.

10
Chapter 1 Introduction to .NET MAUI

XAML Hot Reload


XAML Hot Reload allows you to edit the UI in your XAML files, save the
changes, and observe those changes in your running application without
the need to recompile. This is a fantastic feature that really shines when
you need to tweak some controls.

Performance
.NET MAUI applications are compiled into native packages for each of the
supported platforms, which means that they can be built to perform well.
Android has always been the slowest platform when dealing with
Xamarin.Forms and the team at Microsoft has been working hard and
showing off the improvements. The team has provided some really great
resources in the form of blog posts covering the progress that has been
made to bring the start-up times of Android applications to well below
one second. These posts cover metrics plus tips on how to make your
applications really fly.

• https://devblogs.microsoft.com/dotnet/
performance-improvements-in-dotnet-maui/

• https://devblogs.microsoft.com/dotnet/dotnet-7-
performance-improvements-in-dotnet-maui/

Android apps built using .NET MAUI compile from C# into


intermediate language (IL), which is then just-in-time (JIT) compiled to a
native assembly when the app launches.
iOS and macOS apps built using .NET MAUI are fully ahead-of-time
(AOT) compiled from C# into native ARM assembly code.
Windows apps built using .NET MAUI use Windows UI Library
(WinUI) 3 to create native apps that target the Windows desktop.

11
Chapter 1 Introduction to .NET MAUI

Strong Commercial Offerings


There are several commercial options that provide additional UI elements
and other integrations such as Office document editing or PDF viewing in
your .NET MAUI applications. Some options (at the time of writing) are

• SyncFusion

“The feature-rich/flexible/fast .NET MAUI controls for


building cross-­platform mobile and desktop apps with C#
and XAML”

www.syncfusion.com/maui-controls

• Telerik UI for .NET MAUI

“Kickstart your multiplatform application development with a


Preview version of Telerik UI for .NET MAUI controls!”

www.telerik.com/maui-ui

• DevExpress

“Our .NET Multi-platform App UI Component Library


ships with high-­performance UI components for Android
and iOS mobile development (WinUI desktop support is
coming in 2022). The library includes a Data Grid, Chart,
Scheduler, Data Editors, CollectionView, Tabs, and Drawer
components.”

www.devexpress.com/maui/

Note that while these are commercial products, several of them


provide free licenses for smaller companies or independent developers so
I recommend checking out their products.

12
Chapter 1 Introduction to .NET MAUI

Limitations of .NET MAUI


I hope this doesn’t get me in too much trouble with the wonderful team
over at Microsoft ☺. This section is not aimed at slating the technology (I
wouldn’t be writing a book about something I didn’t believe in); it is purely
aimed at making clear what cannot be achieved or at least what is not
provided out of the box, to help you as a reader best decide whether this is
the right technology for your next project. Of course, I hope it is, but let’s
look at what I feel are its main limitations.

No Web Assembly (WASM) Support


.NET MAUI does not provide support for targeting Web Assembly. This
means that you cannot target the web directly from a .NET MAUI project,
but you can still run Blazor inside your .NET MAUI application. This opens
the door for further code sharing; as discussed earlier, it is entirely possible
to build Blazor components that can be shared between .NET MAUI Blazor
and .NET Blazor applications.
If you do require direct WASM support, then a good alternative to .NET
MAUI is the Uno Platform.

No Camera API


This has been a pain point for a lot of developers throughout the life
of Xamarin.Forms and continues to be an initial pain point for .NET
MAUI. There are some good arguments as to why it hasn’t happened.
Building a camera API against the Android Camera offering has not been
an easy task, as I am sure most developers who have embarked on that
journey can attest to. The sheer fact that Google is rewriting the entire API
for a third time shows the inherent challenges.

13
Chapter 1 Introduction to .NET MAUI

Apps Won’t Look Identical on Each Platform


Controls in .NET MAUI make use of the platform implementations,
therefore an entry control on iOS will render differently to one on Android.
There are investigations into providing a way to avoid this and have
controls render exactly the same on all platforms, but this is still at an
early stage.

Lack of Media Playback Out of the Box


Playing media has become a very common task. So many apps these days
offer the ability to play video or audio. I suspect this is also due to the vast
differences between platforms in how they provide playback support.

While this functionality is not officially provided by .NET MAUI, this


does not mean the functionality is not possible.

The Glass Is Half Full, Though


I believe that limitations are not a bad thing. Doing some things well is
a far better achievement than doing everything badly! I expect the list of
limitations will reduce as .NET MAUI matures. Thanks to the fact that
.NET MAUI is open source, we as consumers have the ability to suggest
improvements and even provide them directly to further enhance this
framework. I must also add that the .NET MAUI Community Toolkit is
great (of course, I am biased because I currently help to maintain it). It
provides value for the .NET MAUI community, and it is also maintained by
that community. Another huge advantage is that concepts in this toolkit
can and have been promoted to .NET MAUI itself. This gives me hope that
one day there will be a solid choice for both camera and media playback
APIs in .NET MAUI.

14
Chapter 1 Introduction to .NET MAUI

How to Build .NET MAUI Applications


There are several different ways to build an application with .NET MAUI. I
will look at each in turn, covering some details that will hopefully help you
decide which is the best fit for you.

Visual Studio
Visual Studio is available for both Windows and macOS, but while these
operating systems are both officially supported, it is worth noting that the
Visual Studio products are separate and themselves not cross-platform.
This means that functionality and levels of support differ between the two.
Note that the Windows and macOS versions come with three different
pricing options, but I would like to draw your attention to the Community
edition, which is free for use by small teams and for educational purposes.
In fact, everything in this book can be achieved using the free Community
edition.

Visual Studio (Windows)


Visual Studio is a comprehensive integrated development environment or
IDE that provides a great development experience. I have been using this
tool for years and I can happily say that it continues to improve with each
new version.
To build .NET MAUI apps, you must use at least Visual Studio 2022.
In Visual Studio (Windows), it is possible to build applications
that target

• Android

• iOS *
• Windows

15
Chapter 1 Introduction to .NET MAUI

* A networked Mac with Xcode 13.0 or above is required for iOS


development and deployment. This is due to limitations in place by Apple.

Visual Studio for Mac


Visual Studio for Mac has only been released recently and as of 2022 it
has undergone a significant rework to provide a better experience for
developers.
To build .NET MAUI apps, you must use at least Visual Studio 2022
for Mac.
In Visual Studio for Mac, it is possible to build applications that target

• Android

• iOS

• macOS

Rider
JetBrains Rider is an impressive cross-platform IDE that can run on
Windows, macOS, and Linux. JetBrains has a history of producing great
tools to help developers achieve their goals. One highlight is ReSharper,
which assists with inspecting and analyzing code. With Rider the
functionality provided by ReSharper is built in.
JetBrains offers Rider for free but only for educational use and open-­
source projects.

Visual Studio Code


Visual Studio Code is a very popular lightweight code editor also provided
by Microsoft. Using extensions and the dotnet CLI, it is entirely possible
to build .NET MAUI applications using no other tools. It is worth noting,
however, that the debugging experience is vastly inferior to the other
products we have discussed.

16
Chapter 1 Introduction to .NET MAUI

Summary
Throughout the course of this book, you will primarily be using Visual
Studio (Windows) as the tool to build your application. I will refer to Visual
Studio for Mac in the later parts when I cover how to deploy and test
macOS applications.
In this chapter, you have learned the following:

• What .NET MAUI is

• What it offers and what it does not offer

• Reasons why you should consider using it

• The tooling options available to build a .NET MAUI


application

In the next chapter, you will

• Get to know the application we will be building


together

• Learn how to set up the environment to build the


application

17
CHAPTER 2

Building Our First


application
In this chapter, you will learn how to set up your development
environment across all of the required platforms. You will then use
that environment to create, build, and run your very first .NET MAUI
application. Finally, you will take a look at the application you will build as
you progress through this book.

Setting Up Your Environment


Before you get into creating and building the application, you must make
sure you have an environment set up.

macOS
There are several tools that you must install on macOS to allow support for
building Mac Catalyst applications and to provide the ability to build iOS
applications from a Windows environment.

© Shaun Lawrence 2023 19


S. Lawrence, Introducing .NET MAUI, https://doi.org/10.1007/978-1-4842-9234-1_2
Chapter 2 Building Our First application

This is required if you wish to develop on macOS or deploy to a Mac


or iOS device (even from a Windows machine). If you are happy with
only deploying to Windows or Android from a Windows machine, then
you can skip this part or just read it for reference.

Visual Studio for Mac


As mentioned in the previous chapter, you will be primarily focusing on
using Visual Studio on Windows. You will have a requirement to use Visual
Studio for Mac much later, but you will set it up now. Also note that while
the book does focus on using Visual Studio on Windows, quite a lot of the
concepts should still translate well enough to Visual Studio for Mac if that
is your preferred environment.
Download and install Visual Studio 2022 for Mac. This can be accessed
from https://visualstudio.microsoft.com/vs/mac/.
1. Open the downloaded
VisualStudioForMacInstaller.dmg file.

2. Double-click the Install Visual Studio for Mac


option. Figure 2-1 shows the Visual Studio for Mac
installer.

20
Chapter 2 Building Our First application

Figure 2-1. Visual Studio for Mac installer

3. You will likely be shown a security dialog making


sure that you wish to run this installer. Double check
the details and then proceed if all looks fine.

4. Accept the terms and conditions by clicking


Continue.

5. In the next window, select .NET, Android, iOS, and


macOS (Cocoa) and then click Install. Figure 2-2
shows the installer with the required options for
.NET MAUI checked.

21
Chapter 2 Building Our First application

Figure 2-2. Visual Studio for Mac installation options

Please refer to the Microsoft documentation page at https://learn.


microsoft.com/dotnet/maui/get-started/installation?tabs=vsmac if
any of the installation options have changed.

Xcode
Xcode is Apple’s IDE for building applications for iOS and macOS. You
don’t need to use Xcode directly, but Visual Studio needs it in order to
compile your iOS and macOS applications.
Thankfully this install is straightforward despite it being a rather large
download.
1. Open the App Store application.

2. Enter Xcode into the Search box and press return.

22
Chapter 2 Building Our First application

3. Click Get. Figure 2-3 shows Xcode available on the


Apple App Store.

Figure 2-3. Xcode on the App Store

4. Once downloaded, open Xcode and wait for it to


install the command line tools. Note that this is
usually required to be performed after each major
update to Xcode, too.

I suggest using caution when applying updates to the whole suite


of applications that you are installing today. Typically, when a new,
big release of .NET MAUI comes out, it likely requires an update of
Xcode. I personally like to keep these expected versions in sync so I
recommend checking for the updates within Visual Studio first and
verifying that it expects a new version of Xcode before proceeding to
update that.

23
Chapter 2 Building Our First application

Remote Access
The final step to set up the macOS environment is to enable remote login
so that Visual Studio (Windows) can communicate to the Mac to build and
run iOS and macOS applications.

1. Open System Settings (macOS Ventura 13.0+) or


System Preferences on older macOS versions.

2. Select General on the left-hand panel and then


Sharing, as highlighted in Figure 2-4. This image
shows the macOS System Settings dialog with the
Sharing menu option highlighted.

24
Chapter 2 Building Our First application

Figure 2-4. macOS system settings

3. Enable Remote Login. Figure 2-5 shows the Remote


Login option enabled.

25
Chapter 2 Building Our First application

Figure 2-5. macOS sharing options

4. Add your user to the list of allowed users for


Remote Login. My user is an Administrator so the
Administrators user group enables remote login
access for this user. Figure 2-6 shows the Remote
Login editor to enable access for users on macOS.

26
Chapter 2 Building Our First application

Figure 2-6. macOS remote login options

5. That’s it! Your mac should now be ready to use.

Windows
Visual Studio
First, you must install Visual Studio 2022. These steps will guide you
through getting it ready to build .NET MAUI applications:

27
Chapter 2 Building Our First application

1. Download and install Visual Studio 2022. This


can be accessed from https://visualstudio.
microsoft.com/downloads/.

2. Run the installer and you will see the workload


selection screen. Select the Mobile development
with .NET workload. Figure 2-7 shows the Visual
Studio Windows installer with the required .NET
MAUI workloads checked.

Figure 2-7. Visual Studio Windows installation options

Please refer to the Microsoft documentation page at https://learn.


microsoft.com/dotnet/maui/get-started/installation?tabs=vswin if
any of the installation options have changed.

Visual Studio to macOS


The final item to configure in your Windows environment is to set up the
connection between Visual Studio and your macOS so that iOS and macOS
builds can be compiled.

28
Chapter 2 Building Our First application

1. Inside Visual Studio select the Tools menu item.

2. Select iOS ➤ Pair to Mac.

3. Check and confirm the firewall access. Figure 2-8


shows the firewall request dialog that is presented
when first running Visual Studio on Windows.

Figure 2-8. Windows firewall request

4. Note that you may also see a second firewall popup


for the Xamarin Broker.

5. Select your Mac from the list.

6. Click Connect. Figure 2-9 shows the Pair to Mac


dialog that allows you to connect your Visual Studio
running on Windows to connect to your macOS
machine.

29
Another random document with
no related content on Scribd:
but we are told, “Labour not to be rich: cease from thine own
wisdom” (Prov. xxiii. 4). One of the various duties of parents towards
their children is to take good care that they learn a trade, and “he
who does not teach his son a trade,” say our Sages, “is as guilty as if
he directly taught him to rob” (Babyl. Talm. Kiddushin, p. 29a).

There is an erroneous opinion abroad, that commerce is more


congenial to Judaism than handicraft. In our Law no trace of such
preference is noticeable; on the contrary, agriculture was the
principal occupation of the Israelites. “When thou eatest the labour of
thine hands, happy art thou, and it is well with thee” (Ps. cxxviii. 2).
“Love work, and hate lordship” is a well-known lesson of the sayings
of the Fathers (Aboth i. 10). Bible and post-Biblical literature equally
teach us the lesson that our comfort and happiness do not depend
on the amount of wealth we have amassed, but on the degree of
contentment our heart has acquired. “Sweet is the sleep of the
labourer, whether he eat little or much: but the abundance of the rich
will not suffer him to sleep” (Eccles. v. 11).

Industry is one of the sources of human happiness; but the blessing


of industry is easily lost, if it is not combined with thrift and
temperance. In days of prosperity we must bear in mind that days of
misfortune may come; we must, so far as we can, provide for them,
so that we may be able to hold out “till the storm has passed.”
Temperance is inseparable from thrift [323]and industry. Intemperance
not only consumes the products of thrift and industry, but in course of
time destroys these very sources of our prosperity. Even with regard
to Sabbath, in honour of which some degree of comfort and even of
luxury may be indulged in, the principle is laid down: “Treat thy
Sabbath like an ordinary day, if additional expense is likely to make
thee dependent on charity” (Babyl. Talm. Shabbath 118a).
3. Knowledge.—God has made man “a little lower than the angels,
and has crowned him with glory and honour” (Ps. viii. 6); He has
endowed him with the faculty of acquiring knowledge: “There is a
spirit in man, and an inspiration of the Almighty, that gives him
understanding” (Job xxxii. 8). It is our duty to cultivate this faculty, to
nurse it with all possible care, that it may grow, produce beautiful
blossoms, and bear goodly fruit. The training must begin very early,
at an age in which we are entirely dependent on the assistance and
guidance of others. Parents, to whom the Almighty has entrusted the
care of their children, are therefore commanded to provide for their
education; and as parents are not always capable of doing this, the
duty devolves on the community or on the State. Every civilised
country has its schools, colleges, and seminaries for the
development of the intellectual and moral faculties of its inhabitants,
and as these institutions increase in number and efficiency, the
prosperity of the nation grows in like proportion. But the success of
these educational institutions, however well provided they may be
with an excellent teaching staff and the best appliances, depends on
the regular and punctual attendance of the children, their attention,
[324]and their industry. It is the duty of parents to see, as far as it is in
their power, that these conditions be fulfilled. Among the various
branches of knowledge we seek to acquire, there is one branch of
paramount importance, the absence of which would make all other
knowledge valueless: it is—

4. Moral and Religious Training.—“The fear of the Lord is the


beginning of knowledge; fools despise wisdom and correction” (‫‏חכמה‬
‫ומוסר‬‎Prov. i. 7). The author of the Book of Proverbs teaches that
knowledge must be combined with ‫‏יראת השם‬‎“fear of God;” and that
it is a perverse idea to separate wisdom (‫‏חכמה‬‎) from moral training
(‫‏מוסר‬‎), and to seek knowledge (‫‏דעת‬‎) without the fear of the Lord
(‫‏יראת ה׳‬‎). Our Sages teach us that our training should include both
fear of God and wisdom. “If there is no wisdom, there is no fear of
God; and in the absence of the latter there is no wisdom” (Aboth iii.
17). Fear of the Lord, however, and fear of sin must have
precedence. Rabbi Chanina, son of Dosa, says: “If a man’s wisdom
is preceded by fear of sin, his wisdom is well established; if the fear
of sin is preceded by wisdom, his wisdom is not well established”
(ibid. 9).

The result of our training must be the acquisition of good manners


and noble principles. Avoid extremes, and hold to the golden mean,
is an excellent rule that leads us safely through the various
conditions of life and wards off many troubles and dangers. The
following examples may serve as an illustration of this rule: Do not
ignore your own self; let self-love and self-respect influence your
conduct; but these must not be allowed to develop into selfishness
[325]and arrogance. Look after your own interests, but do not
consider them as the supreme rulers of your actions. Be self-reliant,
and keep equally far from self-conceit and self-distrust. Haughtiness
and self-contempt are extremes to be avoided: be modest. When
wronged or insulted by your neighbour, be neither callous nor over-
sensitive; ignore insult and wrong in most cases, forgive them readily
in others, and resent them only when forced to do so. In disputes
and discussions be neither weak nor obstinate: be firm. Be neither
passionate nor indifferent: be calm. Do not trust every one, lest your
credulity mislead you; do not suspect every one, lest you become
misanthropic: be discreet. Do not seek danger, nor fear it; but be
prepared to meet it with courage. Be temperate in eating and
drinking, and avoid both excess and needless privation. In spending
your earnings show neither niggardliness nor recklessness: be
economical. Work, but not in such a manner as to ruin your health.
As to your future, be neither too sanguine in your hopes, nor
despondent: do your duty, and trust in God.
There are, however, exceptions from this rule; for in certain cases
there is only the choice between two extremes. Such is Truthfulness.
It is our duty to approach nearer and nearer the extreme of this
virtue, and to consider the least deviation from it as vice. From our
earliest youth we should train ourselves in the practice of this virtue.
Every word that we desire to utter should be well examined before it
passes our lips. We must be on our guard that nothing should
escape our lips that is not in harmony with what we [326]feel or think.
In small matters as well as in important things truthfulness must be
the principle which guides us in our utterances. “The lips of truth
shall be established for ever, but for a moment only the tongue of
falsehood” (Prov. xii. 19). “Keep thee far from a word of falsehood”
(Exod. xxiii. 7). “Falsehood,” say our Sages, “has no legs to stand
upon; whilst ‘truth’ is declared to be the seal of the Holy One,
Blessed be He” (‫‏אמת חותמו של הקב״ה‬‎).

Our moral and religious training is based on the Word of God, on the
Torah, and the study of the Torah, ‫‏חלמוד תורה‬‎, is an essential
element in Jewish education. The term Torah is to be understood in
no narrow sense, but as including the written and the oral Law, all
the books of the Holy Writings, and such works as have from time to
time been composed for the purpose of facilitating and promoting the
study of the Torah. The importance of this duty has been recognised
from ancient times, and Jewish congregations, before building a
synagogue, made provision for the religious education of the young
and for the study of the Law, by establishing schools and colleges
(‫‏בית ספר‬‎or ‫‏בי רב‬‎and ‫‏בית המדרש‬‎).

Talmud-torah is one of those duties to which no measure was fixed


(‫‏אשר אין להם שיעור‬‎Mishnah Peah i. 1). Whenever we can find time
and leisure, we ought to turn to the Word of God, every one
according to his capacity and his opportunities. The readings from
the Torah, both the written and the oral, which form part of our
Service, have been introduced for the purpose of facilitating for the
general public the fulfilment of the duty of Talmud-torah. [327]

The study of the Law and the regular and punctual attendance at the
Beth-hammidrash belong to those religious acts which “bear fruit
here on earth and procure bliss in the future life” (ibid.). Our Sages
exhort us in various sayings to devote ourselves earnestly to the
study of the Torah. The object of this study is, in the first instance, to
enable us to live in accordance with His Commandments; secondly,
to purify our thoughts by turning them from common, ordinary things
to higher and loftier subjects; for while we are reading the Divine
messages and reflecting on them, we move in a purer atmosphere
and must be inspired with holy and noble thoughts.

The book which is expected to produce these results must be


approached “with awe, with meekness, with cheerfulness, and with
purity” (Aboth vi. 6). Our intention must be to be instructed and
guided by what we read. We must not presume to criticise the Divine
decrees therein recorded. If we meet with passages that strike us as
strange or objectionable, we may be sure that we have not yet
comprehended the true sense of the Divine words. Modesty must
cause us rather to assume shortcomings on our part than to find fault
with the Holy Writings. “Turn it over, and read it again and again; for
all is in it, and behold everything through it; and even when old and
weak, cleave to it, and do not move away from it; for there is no
better guide for thee than this one” (Aboth v. 22). There is one great
advantage in the study of the Torah; it constantly supplies us with
one of the best means of promoting our moral training, viz., with
good company.

The society in which we move and the persons [328]with whom we


associate are an important factor in the formation of our character.
Bad companions corrupt us, and lead us to ruin; good companions
improve our moral conduct by their example and not rarely by their
words. “If one joins mockers, he will be a mocker; if he joins the
lowly, he will show grace” (Prov. iii. 34). “Keep away from a bad
neighbour; do not associate with the wicked, and do not believe
thyself safe from evil” (Aboth i. 7). In our daily prayers we ask God
for His assistance in our endeavour to act according to this principle.

The aim and end of all our moral training must be to keep our mind
pure from evil thoughts, to make our heart the seat of noble and lofty
desires; to accustom our tongue to the utterance of that which is
good and true, and to lead a pure, honourable, and godly life. If we
succeed, we establish our well-being during our life on earth, and
secure Divine blessing for our soul in the future world.
[Contents]

III. Signs as Outward Reminders of God’s


Presence.

The voice that comes from within, from our own heart and
conscience, is the best reminder of God’s Presence and Will. But it
does not always sound with sufficient force to make itself heard, and
we, weak mortals, have the weakness of forgetting even most
important duties, unless we are reminded of them from time to time.
The Divine Law has therefore set up signs as outward reminders.
Such are the commandments of ‫‏ציצת‬‎“fringe,” ‫‏תפלין‬‎“ornaments,” and
‫‏מזוזה‬‎“door-post symbol.” [329]

‫‏ציצת‬‎“Fringe” or “Tassel.”

“Thou shalt make thee fringes upon the four corners of thy vesture,
wherewith thou coverest thyself” (Deut. xxii. 12). The object of this
commandment is described as follows:—“It shall be unto you for a
fringe, that ye may look upon it, and remember all the
commandments of the Lord, and do them, and that ye seek not after
your own heart and your own eyes, after which ye use to go astray:
that ye may remember and do all my commandments, and be holy
unto your God” (Num. xv. 39, 40).

In obedience to this commandment, we have two kinds of four-


cornered garments provided with “fringes.” The one is small, and is
worn under the upper garments the whole day; it is called arba’
kanfoth, “four corners,” or talith katan, “small scarf.” The other and
larger one is worn over the garments during the Morning Service. 17 It
is called simply talith, “scarf,” or talith gadol, “large scarf.”

The form of the blessing which accompanies the performance of this


mitsvah varies according as it refers to the small talith or to the large
one. In the former case the blessing concludes with ‫‏על מצות ציצת‬‎
“concerning the commandment of tsitsith;” in the latter with ‫‏להתעטף‬
‫בציצת‬‎, “to wrap ourselves with a garment provided with tsitsith.” 18
[330]

The tsitsith, which is appended to each of the four corners, consists


of four long threads drawn through a small hole about an inch from
the corner; the two parts of the threads are bound together by a
double knot; the largest thread—called shammash, “the servant”—is
then wound seven, eight, eleven, and thirteen times round the other
seven halves of the four threads, and after each set of windings a
double knot is made.—If one of the four tsitsith is not in order, e.g.,
two of the threads being torn off, the talith is called pasul,
“disqualified” for the mitsvah, and must not be worn till that tsitsith is
replaced by a new one.

There is, however, an important element in this Divine


commandment, which is now altogether neglected, viz., “And they
shall put upon the fringe of the corner a thread of ‫‏תכלת‬‎purple blue
wool” (Num. xv. 38). Tradition determined the exact shade of the
purple blue indicated by the term ‫‏תכלת‬‎; in the Talmud (Menachoth
42b) the various ways of its preparation are given. But the colour
seems to have been rare, and we are warned against using
imitations of techeleth. Regulations were also made providing [331]for
the case when techeleth could not be obtained. The natural white
colour was then substituted, and no other colour was allowed. After
the conclusion of the Talmud doubts seem to have arisen as regards
the exact shade of the purple blue demanded by the Divine precept
in the term ‫‏תכלת‬‎, and thus the use of the thread of purple blue wool
gradually ceased to form part of the tsitsith. The exact time when it
ceased cannot be fixed.

‫‏תפלין‬‎19 “Ornaments.”

Four times the Law repeats the commandment concerning the


tefillin: “And thou shalt bind them”—the words of God—“for a sign
upon thy hand, and they shall be for a frontlet between thine eyes”
(Deut. vi. 8 and xi. 18); “And it shall be unto thee for a sign upon thy
hand, and for a memorial between thine eyes, in order that the Law
of the Lord be in thy mouth” (Exod. xiii. 9); “And it shall be for a sign
upon thy hand, and for a frontlet between thine eyes” (ibid. 16).

The object of this commandment is to direct our thoughts to God and


His goodness, and to remind us of the important lessons taught in
the following four paragraphs, in which the commandment of tefillin
is mentioned:—

The(1.)
first paragraph (‫‏קדש‬‎Exod. xiii. 1–10) teaches
[332]that we must, in various ways, express our belief in
God as the King and Ruler of the universe. Two laws are
contained in this paragraph which are to serve this object
—the sanctification of the first-born to the service of the
Lord, and the celebration of the Feast of Unleavened
Cakes.
The(2.)
second paragraph (‫‏והיה כי יביאך‬‎Exod. xiii. 11–16)
reminds us of the wonderful way in which God delivered
our forefathers from Egyptian bondage. Remembering
this deliverance, we are strengthened in our faith in God
in days of trouble, for His ways are not ours, and when
we do not see any prospect of relief God may be
preparing help for us.
The(3.)
third paragraph (‫‏שמע‬‎Deut. vi. 4–9) proclaims the
Unity of God, and teaches us to love God and obey Him
out of love.
The(4.)
fourth paragraph (‫‏והיה אם שמע‬‎Deut. xi. 13–20)
teaches that Providence deals with men according to
their merits, according as each deserves reward or
punishment.

Tradition has handed down to us the way in which this precept is to


be carried out. The four above-mentioned paragraphs are written
twice on parchment, once on one piece, and once on four pieces,
each piece containing one paragraph. The two sets are put into two
leather cases (‫‏בית‬‎), one of which is divided into four compartments,
for the four separate slips of parchment, and marked outside by the
letter shin. 20 Through [333]a loop attached to each bayith a leather
strap (‫‏רצועה‬‎) is passed, the two parts of which are tied together 21 in
such a manner as to hold the bayith on the arm or on the head. On
the arm the case is placed that contains the four paragraphs written
on one piece, on the head that which contains them written on four
pieces. The former is called tefillah shel yad, “tefillin of the hand;” the
latter tefillah shel rosh, “the tefillin of the head.”

The tefillin are put on in the following way:—(1.) Tefillah shel rosh.
The case is placed in front, just over the forehead in the middle, and
the knot of the straps (‫‏קשר‬‎) on the back of the head over the middle
of the neck; the remainder of the two straps hang down in front, one
on each side. (2.) Tefillah shel yad. The case containing the
parchment is placed on the inner side of the left upper arm, near the
elbow; the knot is kept near it, and the strap is twisted seven times
round the arm and three times round the middle finger; there are,
however, different customs with regard to this latter practice.
Tefillah shel yad is put on first, being mentioned first in the Divine
precept. The reverse order is observed in taking off the tefillin.
Originally the tefillin were worn all day long, 22 but at present they are
worn only during the morning prayer. [334]

The tefillin are not worn on Sabbath or Festival. The observance of


these days is “a sign for ever” of our belief “that in six days the Lord
made the heavens and the earth.” The very days of rest thus remind
us of the truths of which the tefillin are “a sign.” The tefillin became,
therefore, unnecessary on those days.

The commandment of tefillin applies to all male persons from their


thirteenth birthday. 23

The performance of this commandment is preceded by the usual


benediction (‫‏ברכת המצות‬‎), concluding ‫‏להניח תפלין‬‎, “to place the
tefillin,” scil., on the arm and on the head. According to the German
rite, a second benediction is recited before placing the tefillah shel
rosh on the head, viz., ‫‏על מצות תפלין‬‎, “concerning the commandment
of tefillin.” 24

In order to prevent a mere perfunctory observance of this


commandment, we are taught to reflect on the importance and the
object of the tefillin, and to declare that by placing the tefillin on the
head and on the arm, near the heart, we indicate our consciousness
of the duty to employ the thoughts that rise in our mind, and the
desires of our heart, in the service of the Lord, who gave us the
powers of thought and will. 25 [335]

‫‏מזּוזה‬‎Door-post Symbol.

The Mezuzah is a piece of parchment on which the two first


paragraphs of Shema (Deut. vi. 4–9, xi. 13–20) are written. The
parchment is rolled together, put into a small case, and fixed on the
right-hand door-post. A small opening is left in the case, where the
word ‫‏ַׁש ַּד י‬‎“Almighty,” written on the back of the scroll, is visible. 26

The object of the mezuzah, commanded in the words, “And thou


shalt write them on the door-posts of thy house and upon thy gates”
(Deut. vi. 9 and xi. 20), is to remind us of the Presence of God, of His
Unity, Providence, and Omnipotence, both on entering our home and
on leaving it; of the all-seeing eye that watches us, and of the
Almighty who will one day call us to account for our deeds, words
and thoughts. The mezuzah thus serves to sanctify our dwelling and
protect it from being polluted by evil deeds.

Signs of God’s Covenant.

Besides the signs mentioned above, there are two other signs of the
covenant between God and Israel.

1. Sabbath is called “an everlasting covenant,” and “a sign between


God and the children of Israel for ever” (Exod. xxxi. 16, 17). See pp.
254 sqq. and 339 sqq. [336]

2. The covenant of Abraham (‫‏ברית מילה‬‎“the covenant of


circumcision”). God made a covenant with Abraham, and said, “Thou
shalt keep my covenant, thou and thy seed after thee in their
generations. This is my covenant which ye shall keep between me
and you, and thy seed after thee: Every male child among you shall
be circumcised when eight days old” (Gen. xvii. 9, 10, 12). If the
eighth day happens to be on a Sabbath, the circumcision takes place
on that day; but if, because of illness, or from any other cause, the
rite has not been performed on the eighth day, it must be done on
some other day, but not on a Sabbath or Festival.

Notes.—1. In reference to the importance of these mitsvoth, Maimonides, in


Mishneh-torah, says as follows:—
“Although we are not commanded to get a talith, and to put it on in order to join the
tsitsith (“fringes”) to it, a religious person will not consider himself free from this
duty, but will always endeavour to wear a garment to which fringes must be affixed.
During prayer we must be especially careful to provide ourselves with a talith. It is
a disgrace for a scholar (Talmid chacham) to say the prayer without the talith. We
must be particularly anxious to perform this mitsvah; it is of great importance with
regard to all the precepts, according to the words, ‘And ye shall look upon it, and
remember all the commandments of the Lord’ ” (2nd Book, Ahabhah, Hilchoth
tsitsith iii. 12).

“The holiness of the tefillin is great, for so long as the tefillin are upon the head and
the arm of a man, he is humble and God-fearing, keeps away from levity and idle
talk, does not conceive evil thoughts, but turns his heart exclusively to words of
truth and justice. We ought therefore to wear them all day long; this would be the
proper way. It is said of Rab, the pupil of Rabbi Jehudah, the Holy, that he was
never seen otherwise than with torah or tsitsith or tefillin.

“Although we ought to wear tefillin all day long, it is our special duty to wear them
during prayer. Our Sages said, ‘He who [337]reads Shema without tefillin rejects,
as it were, his evidence concerning the Almighty as false’ ” (ibid., Hilchoth tefillin iv.
26).

“We should be particular with regard to the mezuzah, which is a duty incumbent
uninterruptedly on every one. Whenever we enter or leave the house our eye
meets with the name of God; we remember His love, and rousing ourselves from
our torpitude, we are led to regret our foolish devotion to the vanities of the time,
and recognise that nothing remains for ever except the knowledge of the Rock of
the universe. We shall then at once devote ourselves to know Him, and walk in the
way of uprightness. Our ancient Sages said, ‘He who has tefillin upon his head
and upon his arm, tsitsith on his garment, and mezuzah on his door, he is safe
from sin, since he has many reminders of his duties, and these are the angels that
protect him from going astray; and to him the following verse applies: “An angel of
the Lord encampeth round those who fear Him” ’ ” (ibid., Hilchoth mezuzah vi. 13).

2. The great importance of the tefillin, as described by Maimonides, was not


understood or recognised by all Jews. Various sayings occurring in the Talmud
indicate the existence of laxity or even opposition with regard to the carrying out of
this precept in its literal sense. When persons with tefillin on their head and on
their arm showed by their conduct that their heart was not filled with the holiness
and uprightness of which the tefillin are the symbol, it was but natural that not only
were these persons accused of hypocrisy, but the Divine precept itself was
discredited. But the greater the opposition by one section of the Jewish
community, the more the enthusiasm of the other section grew in its favour. Hence
the numerous Talmudical and Rabbinical utterances concerning the sanctifying
force inherent in the tefillin (comp. Tur Orach Chayyim xxxvii.). Thus, when a
Rabbi was cautioned not to be over joyous, as excess of joy led to sin, he replied,
“I lay tefillin;” i.e., “The thoughts which the observance of this precept awakens
protects me from sin.” This idea of protection from sin may be the origin of the
Greek name phylacterion, “protection.”—In times of persecution, when the Jews
were forbidden by their oppressors to perform any of their religious rites on penalty
of death, the precept of tefillin was not included among those which they
performed even at the risk of their life. To this circumstance Rabbi Simeon b.
Elazar ascribes the laxity with regard to the tefillin (Babyl. Talm. Shabbath 130a).
[338]

3. There occurs in the Midrash (Sifre on Deut. xi. 18), in reference to tsitsith and
tefillin, the following passage: “Also when in exile deck yourselves with mitsvoth, in
order that on your return to your own land the Divine precepts should not seem to
you new and unknown.” This passage has been misinterpreted as if the author of
that passage were of opinion that precepts like tsitsith and tefillin did originally not
apply to those who are outside the Holy Land. The meaning is rather this: Although
a large portion of the laws is not in force outside Palestine, yet continue to wear
these reminders in exile, in order that by this act your attention may constantly be
turned to the whole Torah, to those precepts which are in force at present as well
as to those which are not. Thus all the precepts will be familiar to you, and when
the time comes in which the observance of all the laws will again be possible, none
of the laws will appear to you new and strange.

4. There is, on the whole, no difference between men and women with regard to
the obedience due to the Divine commandments. All Jews are equally bound to
obey the Will of God expressed in the Law. This is absolutely the case with all
prohibitions (‫‏לא תעשה‬‎). In the case of positive commandments (‫‏מצות עשה‬‎) the
following rule has been laid down by our Sages: Women are exempt from the
performance of such religious duties as are restricted to a certain period of time
(‫‏מצות עשה שהזמן גרמא נשים פטורות‬‎). The object of the seeming anomaly is probably
this: the principal duty and the privilege of women is to manage the household, a
task that demands constant attention. Religious acts which are to be performed at
a certain time might involve an interference with such of their household duties as
demand immediate attention; e.g., nursing a patient, a task which generally falls to
the lot of the female section of the family. Jewish women, nevertheless, zealously
fulfil most of the duties from which the above rule exempts them. They thus are
most eager to obey the laws concerning shofar on New-year, lulab on Tabernacles,
and the like; and some of them are named as having conscientiously laid tefillin
(Mechilta on Exod. xiii. 9). [339]
[Contents]

IV. Sabbath and Festivals.

The daily work which has chiefly the well-being of the body as its aim
must be interrupted on certain days which the Almighty has
appointed for the promotion of man’s spiritual well-being. Sabbath
and Festivals are the days thus appointed, and are therefore called
‫‏מועדי יי‬‎“the seasons of the Lord,” and ‫‏מקראי קדש‬‎“holy convocations.”
The blessing derived from the observance of Holy-days in the true
spirit is described by the prophet as follows: “If thou keep back thy
foot because of the sabbath, from doing thy business on my holy
day; and call the sabbath a delight, the holy of the Lord, honourable,
and shalt honour it, not doing thine own ways, nor finding thine own
business, nor speaking thine own words: then thou shalt delight
thyself in the Lord: and I will cause thee to ride upon the high places
of the earth, and feed thee with the heritage of Jacob, thy father”
(Isa. lviii. 13, 14). To those who fail to observe the seasons of the
Lord in the true spirit, the prophet says in the name of the Almighty:
“Your new-moons and your festivals my soul hateth: they are a
trouble unto me; I am weary to bear them” (ibid. i. 14).

Maimonides 27 comprehends the various duties and observances of


the Holy-days in the following four terms: ‫‏זכור‬‎“remember,” ‫‏שמור‬‎“take
heed,” ‫‏כבוד‬‎“honour,” and ‫‏עונג‬‎“delight.” The first two are found in the
Pentateuch, and form the beginning of the fourth commandment in
Exodus and Deuteronomy respectively; the other two occur in the
above description [340]of the Sabbath quoted from Isaiah (lviii. 13,
14). Following the example of our great teacher, we shall likewise
treat of the laws and customs of Sabbath and Festivals under these
four heads: 28—

a. ‫‏זכור‬‎“Remember.”

Remember the Sabbath-day; speak of it, of its holiness and its


blessings. We fulfil this duty when Sabbath comes in, by the
Kiddush, “the sanctification of the day,” in which we praise the
Almighty for the boon bestowed upon us by the institution of the
Sabbath; and when Sabbath goes out, by the Habhdalah, in which
we praise God for the “distinction” made between the holy and the
ordinary days. We have both Kiddush and Habhdalah in a double
form: (a) as a portion of the Amidah in the Evening Service; the
Kiddush being the middle section of the Amidah, the Habhdalah
consisting of a prayer added to the fourth paragraph beginning ‫‏אתה‬
‫חנן‬‎; (b) as a separate service especially intended for our homes. It is
this home-service that we generally understand by the terms
Kiddush and Habhdalah, and in this sense they are employed in the
following. 29

Kiddush.

There is a traditional explanation of the term zachor: ‫‏זכרהו על היין‬‎


“remember it over the wine.” As “wine [341]gladdens the heart of man”
and forms an important element in a festive meal, it has been
ordered that our meal on the eve 30 of Sabbath and Festival should
be begun with a cup of wine in honour of the day, and that mention
should be made of the holiness of the day before partaking of the
wine. The Kiddush consists of two blessings (‫‏ברכות‬‎): one over the
wine, 31 and one that refers to the holiness of the day. On Holy-days
—except the last days of Passover—a third blessing (‫‏שהחינו‬‎) follows,
praising God for having granted us life and enabled us again to
celebrate the Festival. On Friday evening a portion from Genesis (i.
31 to ii. 3) is added, which contains the first mention of the institution
of Sabbath. If a Festival happens to fall on Sunday, we add part of
the Habhdalah to the Kiddush on Saturday evening, 32 [342]referring to
the distinction between the holiness of the Sabbath and that of the
Festivals.

The Kiddush is part of the Sabbath or Festival evening meal, and in


the absence of the latter the Kiddush is omitted. 33 In Synagogues of
the German and Polish Minhag the Reader recites the Kiddush at
the conclusion of the Maarib Service. This custom is a survival of the
ancient way of providing for the poor and the stranger. In the
absence of better accommodation lodging and food were given to
the needy in rooms adjoining the Synagogue, or even in the
Synagogue itself. It was for these that the Reader recited the
Kiddush, before they commenced the evening meal, as most
probably wine was not served to all. Although circumstances have
changed the mode of maintaining the poor, and the latter find no
longer lodging and board in the Synagogue, the Kiddush has been
retained as part of the Maarib Service, except on the first two nights
of Passover, when there had never been an occasion for reading
Kiddush in the Synagogue. The poor were treated on these nights
with four cups of wine each, and they recited Kiddush by themselves
as part of the Seder. [343]

Habhdalah ‫‏הבדלה‬‎.

Habhdalah is recited in the evening following Sabbath or Holy-day,


after the Evening Service. A cup of wine is raised, and the ‫‏ברכה‬‎over
wine is followed by another ‫‏ברכה‬‎, in which God is praised for the
distinction made between the holy and the ordinary day (‫‏בין קדש‬
‫לחול‬‎), or between two kinds of holiness (‫‏בין קדש לקדש‬‎) in case
Sabbath is followed by a Holy-day.—On Sabbath night we take a
candle and a spice-box, and add two blessings after that over wine;
in the one we thank God for the enjoyment of the fragrance, in the
other for the benefit He bestowed on us by the creation of light. A
few verses from the Bible, especially the Prophets, precede the
Habhdalah.

The origin of the introduction of the blessings for light and for spices
in the Habhdalah may be the following:—The principal meal of the
day used to be taken about sunset; light and burning incense were
essential elements of a festive meal. On Sabbath these could not be
had, and were therefore enjoyed immediately after the going out of
Sabbath. Although the custom of having incense after the meal has
long ceased, it has survived in the Habhdalah, and has, in course of
time, received another, a more poetical interpretation. The Sabbath
inspires us with cheerfulness, gives us, as it were, an additional soul
—‫‏ְנ ָׁש ָמ ה ְיֵת ָר ה‬‎—traces of which are left on the departure of Sabbath,
and are symbolised by the fragrance of the spices. For the use of the
special light there has likewise been suggested a second reason,
namely, that it is intended at the commencement [344]of the week to
remind us of the first product of Creation, which was light.

There are a few customs connected with the Habhdalah that may be
noticed here.

(1.) The wine, when poured into the cup, is allowed to flow over, as a
symbol of the overflowing Divine blessing which we wish and hope to
enjoy in the coming week.

(2.) Some dip their finger in wine and pass it over their eyes, in
allusion to the words of the Nineteenth Psalm (ver. 9), “The
commandment of the Lord is pure, enlightening the eyes.” The act
expresses the love of the Divine commandments (‫‏ִח ּבּוב ִמ ְצ ָוה‬‎).
(3.) Only male persons partake of the wine; they have more interest
in the Habhdalah as the signal for the resumption of ordinary work
and business.—The exclusion of women from the wine of Habhdalah
may also have its origin in the fact that Jewish women generally
abstained from taking wine, considering strong drink suitable only for
the male portion of mankind. They only partake of the wine of
Kiddush on account of its importance; to Habhdalah less importance
was ascribed.

(4.) On reaching the words ‫‏בין אור לחשך‬‎, “between light and
darkness,” some hold their hands against the light, the fingers bent
inside, in illustration of the words which they utter, showing darkness
and shadow inside and light outside.—With the practice of these and
similar customs we must take good care that we should not combine
any superstitious motive, or join actions which are really
superstitious, and did not originate in Jewish thought and Jewish
traditions. [345]

We further remember the Sabbath-day to sanctify it by increased


devotion, by reading special Lessons from the Pentateuch and the
Prophets, and by attending religious instruction given by teachers
and preachers.

Besides various additions in the Service, and the substitution of one


paragraph concerning Sabbath or Festival for the thirteen middle
paragraphs of the Amidah, there is another Service inserted between
the Morning and the Afternoon Services; it is called Musaph, “the
Additional Service,” and corresponds to the additional offering
ordained for Sabbath and Festival (Num. xxviii. 9, sqq.).

An essential element in the Morning Service is the Reading from the


Torah (‫‏קריאת התורה‬‎) and the Prophets (‫‏הפטרה‬‎). A periodical public
reading from the Law was enjoined in the following words: “At the
end of every seven years, in the solemnity of the year of release, in

You might also like